Hexo + NexT + Github：搭建博客

发表于 更新于 分类于 阅读次数：

在开始之前，首先理清一下 Hexo、NexT 和 Github 三者的关系：

  • Hexo 本身是自动生成博客网页的框架代码，它不需要我们自己编写网页（例如 .css，.js ），而是修改 _config.yml 文件提供的参量，自动生成静态网页，可以在本机浏览。
  • NexT 是 Hexo 的主题插件，本身依赖于 Hexo，提供额外的主题。它同样也提供 _config.yml 文件供我们配置。
  • 使用 Github 将生成的静态网页推送到互联网当中。

新版本的 NexT 可以在博客根目录下配置 _config.next.yml 文件，这可以避免在使用 Github 更新 NexT 时与本地的配置文件发生冲突，同时也不再用区别 Hexo 和 NexT 名称相同的配置文件。

安装 Hexo

Hexo 的官方配置文档在这里。首先安装一些必备的工具：Node.js；Git，然后使用 npm 安装 Hexo，

1
npm install -g hexo-cli

初始化博客本地文件夹

现在需要在本机的某一文件夹下初始化博客，例如想将博客文件放在 Blog/ 目录下，在该文件夹中打开命令行，运行如下命令

1
hexo init

运行上述命令之后，在 Blog/ 文件夹下会生成如下子目录结构：

1
2
3
4
5
6
7
8
.
├── _config.yml
├── package.json
├── scaffolds
├── source
|   ├── _drafts
|   └── _posts
└── themes
  • 如果在 Windows 环境下第一次使用 Hexo 命令时，可能会报关于 PowerShell 不能信任 Hexo 脚本的错误，并在界面中指向网址。直接把执行策略改成 Bypass
1
Set-ExecutionPolicy -ExecutionPolicy Bypass

在默认设置之外的配置

详细的配置步骤可见 Hexo 和 NexT 官方文档，不过更推荐看 NexT 的文档，因为 NexT 的文档中既包含了 Hexo 的配置，同时一直在更新当中。这里列举了我的博客在默认设置之外的配置。

自定义菜单栏内容

NexT 提供的菜单栏内容如下：

1
2
3
4
5
6
7
8
9
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

如果要添加分类和标签页，首先使用如下命令生成对应的博客页面：

1
2
hexo new page categories
hexo new page tags

在 source/ 目录下会多出 source/categories/index.md 和 source/tags/index.md，为了在博客页面中显示文档的分类和标签，还需要修改头部的代码如下：

1
2
3
4
5
6
 ---
title: 分类
date: 2024-04-10 23:40:31
type: "categories"
comments: false
 ---
1
2
3
4
5
6
 ---
title: 标签
date: 2024-04-10 23:40:31
type: "tags"
comments: false
 ---

如果希望加入额外的标签页，新建标签如下：

1
nichijou: /nichijou/ || fa-regular fa-sun

其中 fa-regular fa-sun 是来自 font awesome 的图标。这时我们还需要配置语言，使得 NexT 能够识别关键词，在 ./theme/next/language 目录下找到 zh-CN.yml，在 menu 关键词下添加如下翻译词对：

1
2
# add user defined translation pair
nichijou: 日常

在修改完配置文件之后，我们还需要生成博客 page 页面对应的 .md 文档，使用如下命令：

1
hexo new page nichijou

之后会在 ./source 目录下生成同名目录 nichijou/，同时在该目录中生成 index.md 文件。这样在点击博客菜单栏标题时，就会显示 index.md 的内容。

公式显示

hexo 在生成静态网页时不会编译 LaTeX 相关公式，而是将文档翻译成数学相关 Jave 库能够解析的形式，例如 MathJax 或 KaTeX。hexo 默认使用 hexo-renderer-marked，但是该渲染器可能会错误地转义公式中的特殊字符，因此这里我改用 pandoc 进行渲染。首先需要修改 _config.next.yml 关于 math 部分的配置如下：

1
2
3
4
5
6
7
8
9
10
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 script EVERY PAGE.
  every_page: true

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

然后卸载 hexo-renderer-marked，安装 pandoc 和 hexo-renderer-pandoc，

1
2
3
npm un hexo-renderer-marked
# 在安装 pandoc 渲染器之前，先安装 pandoc @https://pandoc.org/installing.html
npm i hexo-renderer-pandoc

在安装完渲染器之后，还需要再进入到 hexo 配置文件中配置调用 pandoc 进行渲染时使用 MathJax，

1
2
3
4
# config of hexo-renderer-pandoc
pandoc:
  args:
    - --mathjax

这个网址给出了最新的 MathJax 文档。

知识协议

配置的协议为 cc by-sa，可以共享、修改、用于商业目的，但是必须在引用时指明来源，并且使用相同的协议。

撰写博客的工作流程

以下按照撰写博客文章的流程，给出对应的 hexo 命令。

新建博客文档

新建文档的命令是 new

1
hexo new [layout] <title>
  • 可选参数 [layout]：默认是 post，可以选择为 draft，这时会在 \source\_drafts 目录下生成待发表的博客文档，并且没有时间戳；
  • 文档题目 <title>：可以不添加后缀，默认生成 <title>.md 文档。如果题目中没有空格，也可以不用加双引号。

例如新建文档 测试我的第一篇博客文档

1
hexo new 测试我的第一篇博客文档

这样就可以在 \source 目录下找到对应的 测试我的第一篇博客文档.md 文档了。如果不想立即发表博客文档，可以使用如下命令：

1
hexo new draft "博客草稿"

这时在生成网站文件时会自动忽略该文档。如果该草稿已经完成，则使用如下命令进行发表，hexo 会将该文档转移到 \source\_posts 目录下：

1
hexo publish post "博客草稿"

此外还可以在 \scaffold 目录下自定义模板文件，具体详见 hexo 写作 文档。

生成网站文件

首先先使用如下命令清理原来的站点文件：

1
hexo clean

或简写为

1
hexo cl

然后运行如下命令生成静态文档：

1
hexo generate

或简写为

1
hexo g

后面还可以加一点组合命令，比如 -d 表示生成完静态站点之后直接推送到 Github 上去，它与如下命令是等价的：

1
hexo deploy -g

这个命令意思是在 deploy 之前先 generate。如果想在本机中查看网页生成的效果，可以运行

1
hexo server

总结

在配置完成之后，上传一篇博客文档的工作流程可以总结为：

  1. 在 目录中生成 博客文档.md 文件：hexo new <博客文档名称>。
  2. 编写 博客文档.md 文档。（可以不在 Hexo 生成的 .md 文件中编写，只需完成后将文档内容复制到该文件中即可）
  3. 清除生成的静态文件：hexo cl。
  4. 重新生成静态文件：hexo g。
  5. 查看生成网页的效果，若不满意，则返回第 2 步：hexo s。
  6. 上传到 Github，博客的内容最终展示在互联网上：hexo d。