利用 hexo 实现静态托管网页

Posted on Edited on In Views:
利用 hexo 实现静态托管网页的一些问题

静态托管网页搭建

0. 一些说明

  • 基于 Hexo 进行搭建
    • https://hexo.io/zh-cn/
  • 需要的组件
    • Git
    • node.js
  • 我的版本信息
部件 版本
node.js v16.18.0
npm 8.19.2
Git git version 2.38.1.windows.1

1. 安装 Hexo

  • 建议全局安装 hexo
    • 其他的插件只需要安装在局部即可
1
npm install hexo-cli -g
  • 如果下载不下来的话可以换源
1
2
3
4
# 仅本次安装换源
npm --registry https://registry.npm.taobao.org install hexo-cli -g
# 永久换源
npm config set registry https://registry.npm.taobao.org
  • 需要将 hexo 所在的目录添加到环境变量
    • 安装 npm 的时候应该会自动进行这一步
1
2
3
4
5
# 查看所有配置信息
# npm config ls

# 查看 bin 目录
npm config get prefix

2. 开始我们的快乐

  • 如果命令太慢的话可以直接对 npm 换源
1
2
# 永久换源
npm config set registry https://registry.npm.taobao.org
  • 新建一个空白文件夹
    • 之后的命令行操作均在该文件夹目录下进行
1
2
hexo init
npm install
  • 生成页面
1
hexo g
  • 预览页面
1
hexo s
  • 指定端口打开预览
1
hexo s -p 5000

3. 部署 Hexo 到 GitHub Pages

  • 安装 hexo-deployer-git
    • 这里是安装在局部
1
2
npm install hexo-deployer-git --save
# npm install hexo-deployer-git
  • --save
    • npm 5.0.0 之前，有 --save 参数才会把模块写入到 packages.json
    • 现在不需要写了
  • 修改配置文件 _config.yml 的 Deployment 部分
1
2
3
4
# Deployment
## Docs: https://hexo.io/docs/one-command-deployment
deploy:
  type: ""
1
2
3
4
5
6
# Deployment
# Docs: https://hexo.io/docs/one-command-deployment
deploy:
  type: git
  repository: git@github.com:banbao991/banbao991.github.io.git
  branch: main
  • 将 "banbao991" 修改为你自己的用户名即可
  • 上传
1
hexo d
  • 没有权限上传
    • 需要有 repo 的访问权限
    • 需要配置本地 git 的 ssh key
      • 配置方法
      • 这里配置好了之后，repo 之后可以使用 git 而不是 http 下载，不易被墙

4. 其他

4.1 新建文件

1
hexo new "New.File"
  • 然后进入文件夹 source/_posts 编辑即可

4.2 修改主题

  • 例如 NexT
1
git clone git@github.com:next-theme/hexo-theme-next.git themes/nexT
  • 修改配置文件 _config.yml 的 Extensions 部分
1
2
3
4
# Extensions
## Plugins: https://hexo.io/plugins/
## Themes: https://hexo.io/themes/
theme: landscape
1
2
3
4
# Extensions
## Plugins: https://hexo.io/plugins/
## Themes: https://hexo.io/themes/
theme: nexT

  • 支持 Latex

    • 修改 nexT 的主题的配置文件 _config.yml

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    math:
      # Default (false) will load mathjax / katex script on demand.
      # That is it only render those page which has `mathjax: true` in front-matter.
      # If you set it to true, it will load mathjax / katex srcipt EVERY PAGE.
      every_page: false

      mathjax:
        enable: false
        # Available values: none | ams | all
        tags: none

      katex:
        enable: false
        # See: https://github.com/KaTeX/KaTeX/tree/master/contrib/copy-tex
        copy_tex: false

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    math:
      every_page: false

      mathjax:
        enable: true
        tags: none

      katex:
        enable: true
        copy_tex: false

    • 然后在需要进行渲染的 markdown 文件开头加上 mathjax: true

4.3 nexT 主题细节

(1) 网页配置文件

  • _config.yml
[1] 主题
1
2
3
4
5
# Schemes
# scheme: Muse
# scheme: Mist
# scheme: Pisces
scheme: Gemini

(2) nexT 主题配置文件

  • themes/nexT/_config.yml
[1] 菜单
1
2
3
4
5
6
7
8
9
10
11
# 格式: 目录 || 图标

menu:
  home: / || fa fa-home
  # about: /about/ || fa fa-user
  tags: /tags/ || fa fa-tags
  categories: /categories/ || fa fa-th
  archives: /archives/ || fa fa-archive
  # schedule: /schedule/ || fa fa-calendar
  # sitemap: /sitemap.xml || fa fa-sitemap
  # commonweal: /404/ || fa fa-heartbeat
[2] 目录
1
2
3
4
5
6
7
toc:
  enable: true
  number: false  
  # 给标题添加标号
  wrap: false
  expand_all: false
  max_depth: 6
[3] 头像
  • 头像
1
2
3
4
avatar:
  url: /images/avatar.jpg
  rounded: true
  rotated: false
  • 顶部 icon
1
2
3
4
5
6
favicon:
  small: /images/favicon-16x16-next.jpg
  medium: /images/favicon-32x32-next.jpg
  apple_touch_icon: /images/apple-touch-icon-next.jpg
  safari_pinned_tab: /images/logo.svg
  # android_manifest: /manifest.json
  • 每次执行 hexo clean 之后重新执行 hexo g 生成文件时会把这些图片文件删除
  • 解决方案如下
    • 将这些图片放置到 themes/nexT/source/images 文件夹下，这样便可以通过 hexo g 生成
[4] 访问次数
  • 出现数字不对是本地的问题，在线就没事
1
2
3
4
5
6
7
8
busuanzi_count:
  enable: true
  total_visitors: true
  total_visitors_icon: fa fa-user
  total_views: true
  total_views_icon: fa fa-eye
  post_views: true
  post_views_icon: far fa-eye
[5] 暗色系
  • darkmode
1
2
# Dark Mode
darkmode: true
[6] 点击图片放大
1
fancybox: true
[7] 阅读进度条
1
2
3
4
5
6
7
8
9
reading_progress:
  enable: false
  # Available values: left | right
  start_at: left
  # Available values: top | bottom
  position: top
  reversed: false
  color: "#37c6c0"
  height: 3px
[8] github_banner
1
2
3
4
github_banner:
  enable: true
  permalink: https://github.com/banbao990
  title: Follow me on GitHub

(3) 其他细节

修改 p 的 margin
  • 文件：themes\nexT\source\css\_common\scaffolding\base.styl
1
2
3
p {
  margin: 0 0 20px;
}
1
2
3
p {
  margin: 0;
}
mathjax 显示不完全
  • 打开文件 \themes\nexT\source\css\_common\components\third-party\math.styl
1
2
3
4
5
6
7
mjx-container[jax="CHTML"][display="true"], .has-jax {
  /* overflow: auto hidden; */
}

mjx-container[display="true"] + br {
  display: none;
}
latex 换行问题
  • 需要在 latex 中书写 \\\\ 才表示 换行
  • 换个渲染引擎
1
2
npm uninstall hexo-renderer-marked
npm install hexo-renderer-pandoc
  • 发现渲染的时候还是会报错，奇奇怪怪的错误

4.4 添加分类模块

1
hexo new page tags
  • 此时会在 source/tags 文件夹下生成一个 index.md 文件
  • 打开这个文件，顶部加上一句
1
type: "tags"
  • 按照 (2)->[1] 设置显示 tags 标签即可
  • 添加 categories 模块
1
type: "categories"

4.5 插入图片

1
npm install hexo-asset-image
  • 根目录的配置文件
1
post_asset_folder: true
  • 之后新建 md 文件的时候便会同时新建一个为同名文件夹，用于保存引用的图片
  • 但是存在一个问题，图片路径不一致
  • 解决方案如下
  • 打开文件 node_modules/hexo-asset-image/index.js
  • 修改如下
1
2
3
4
5
6
7
if(/.*\/index\.html$/.test(link)) {
    appendLink = 'index/';
    var endPos = link.lastIndexOf('/');
}
else {
    var endPos = link.lastIndexOf('.');
}
1
2
3
4
5
6
7
if(/.*\/index\.html$/.test(link)) {
    appendLink = 'index/';
    var endPos = link.lastIndexOf('.');
}
else {
    var endPos = link.lastIndexOf('/');
}

4.6 github 挂载和本地不一致

  • css/js 等问题
1
2
hexo clean
hexo d -g
  • 注意头像文件等的保存

4.7 将文件的路径转变为数字

  • 方便引用
  • https://github.com/Rozbo/hexo-abbrlink
  • 安装插件 hexo-abbrlink
1
npm install hexo-abbrlink --save
  • 不使用，有点乱

4.8 配置 mermaid

  • 下载安装插件 hexo-filter-mermaid-diagrams
1
npm install hexo-filter-mermaid-diagrams
  • 修改配置文件 _config.yml（根目录下的文件）
    • 在最后添加（因为我的部分没有 mermaid 部分）
1
2
3
4
5
6
# mermaid chart
mermaid: ## mermaid url https://github.com/knsv/mermaid
  enable: true  # default true
  version: "7.1.2" # default v7.1.2
  options:  # find more api options from https://github.com/knsv/mermaid/blob/master/src/mermaidAPI.js
    #startOnload: true  // default true
  • 修改配置文件 _config.yml（主题目录下的文件）
    • themes/nexT/_config.yml
    • 将 mermaid 模块下的 enable 修改为 true
1
2
3
4
5
# Mermaid tag
mermaid:
  enable: true # 从 false 修改为 true
  # Available themes: default | dark | forest | neutral
  theme: forest
  • 修改 js 文件（现在似乎不需要修改了，已经加入到 hexo 标准里面了）
    • themes/nexT/layout/_partials/footer.njk
    • 在文件最后添加如下代码
      • 不太理解为啥 theme.mermaid.version === undefined 是 true
1
2
3
4
5
6
7
8
9
10
11
12
{% if (theme.mermaid.enable)  %}
  {% if (theme.mermaid.version === undefined)  %}
    <script src='https://unpkg.com/mermaid/dist/mermaid.min.js'></script>
  {% else  %}
    <script src='https://unpkg.com/mermaid/dist/mermaid@{{theme.mermaid.version}}.min.js'></script>
  {% endif  %}
    <script>
      if (window.mermaid) {
        mermaid.initialize({theme: 'forest'});
      }
    </script>
{% endif %}

4.9 搜索功能

  • 安装插件
1
npm install hexo-generator-searchdb
  • 在全局配置文件 _config.yml 中增加如下项
1
2
3
4
5
search:
  path: search.xml
  field: post
  format: html
  limit: 10000
  • 修改主题文件的配置，我使用的是 nexT
  • hexo 主题配置文件 \themes\nexT\config.yml，修改 local_search 的enable 为 true
1
2
3
4
5
6
7
8
9
10
11
12
13
# Local Search
# Dependencies: https://github.com/next-theme/hexo-generator-searchdb
local_search:
  enable: true
  # If auto, trigger search by changing input.
  # If manual, trigger search by pressing enter key or search button.
  trigger: auto
  # Show top n results per article, show all results by setting to -1
  top_n_per_article: 1
  # Unescape html strings to the readable one.
  unescape: false
  # Preload the search data when the page loads.
  preload: false

4.10 某个文件夹下的 html 文件不渲染

  • 根目录下的 _config.yml 文件，修改内容
1
2
3
4
5
6
skip_render: 
  - utils/**/*
  - resources/**/*
  - libs/**/*
  - kits/**/*
  - use/**/*

4.11 忽略某些文件夹下文件

  • 根目录下的 _config.yml 文件，修改内容
1
2
exclude:
  - kits/**/*.class

4.12 LF 替换为 CRLF 刷屏

1
2
warning: LF will be replaced by CRLF in page/3/index.html.
The file will have its original line endings in your working directory
  • 以上信息刷屏
1
git config --global core.autocrlf false

5. 参考资料