Hexo站点基本配置与实用工具指北

发表于 更新于 分类于 阅读次数： 本文字数： 1.8k 阅读时长 ≈ 5 分钟
本文章记录Hexo博客站初始化后，需要对博客站进行一些基本配置，以便后续使用(其中包含许多踩过的大坑)。

读前须知

阅读该文章时，应该已经完成博客站的初始化配置，若未进行初始化配置，请阅读前置文章Hexo + Github Pages建站指北。

由于不同版本环境配置不尽相同，先贴出我使用的系统环境如下：

  • Hexo: 5.4.0
  • Git: 2.29.2.windows.3
  • Node.js: 15.4.0

站点配置文件详解

主要修改站点配置文件 _config.yml 来实现个性化。

网站基本信息

网站基本信息修改的字段如下图所示：

1
2
3
4
5
6
7
title: # 网站标题
subtitle: # 网站副标题
description: # 网站描述
keywords: # 网站关键词，支持多个关键词
author: # 作者名称
languages: # 语言，中文采用zh-CN, 英文采用en
timezone: # 中国大陆地区采用"Asia/Shanghai"，注意城市不能随意修改

URL配置

主要用于站点链接配置。

1
2
3
4
5
6
# URL
## Set your site url here. For example, if you use GitHub Page, set url as 'https://username.github.io/project'
url: https://username.github.io/project # 替换自己的用户名即可
root: / # 保持不变
permalink: :year/:month/:day/:title/ # 网站的永久链接，可根据自己的喜好调整
permalink_defaults:

由于我们写文章时title可能含有中文，因此会生成含有中文的url，这会造成许多不可预料的问题。于是采用另外的方式来生成永久链接。

首先键入以下命令安装相应插件：

1
npm install hexo-abbrlink --save

接着修改站点配置文件 _config.yml 中的 permalink 字段。

1
2
3
4
permalink: posts/:abbrlink/
abbrlink:
	alg: crc32   # 算法： crc16(default) and crc32
	rep: hex     # 进制： dec(default) and hex

这样就完成了永久链接的修改，文章在发布时会被自动分配16进制代码。

写作配置

主要在新建与发布文章时使用。

1
2
3
4
5
6
7
8
9
new_post_name: title.md # 新建post时的文件名
default_layout: post # 默认采用模板
highlight: # 高亮设置
  enable: true
  line_number: true
  auto_detect: true
  tab_replace: ''
  wrap: true
  hljs: false

翻页配置

主要用于控制文章排序以及每页显示的数量。

1
2
3
4
5
# Home page setting
index_generator:
  path: '' # 用于设置站点根目录，一般不用修改
  per_page: 10 # 每页显示的文章数量，建议10或12，0表示所有文章平铺
  order_by: -date # 排序依据，默认为发布时间降序

部署配置

主要用于连接GitHub，设置推送的远程仓库。

1
2
3
4
5
6
# Deployment
## Docs: https://hexo.io/docs/one-command-deployment
deploy:
  type: git # 统一填写git
  repo: git@github.com:BXJC/BXJC.github.io.git # 输入自己的repo地址
  branch: master # 选择仓库中的默认分支

站点页面初始化

在站点配置文件修改完成后，网站的tags、categories等页面仍无法正确跳转，需要进行页面初始化配置。

新建标签页面

在Git Bash里键入以下命令：

1
$ hexo new page "tags"

此时，hexo会在 Hexo/source/ 下创建一个tags目录，并在其中放置index.md文件。

打开index.md文件，修改其meta属性，添加如下内容：

1
type: "tags"

在本地调试后，即可发现tags页面跳转正常。

在文章写作过程中，可以在meta数据中的tags字段后添加[]来放置tags，支持多个标签，每个标签之间使用半角英文逗号分割,如：

1
tags: [Hexo, Next]

新建分类页面

在Git Bash里键入以下命令：

1
$ hexo new page "categories"

此时，hexo会在 Hexo/source/ 下创建一个categories目录，并在其中放置index.md文件。

打开index.md文件，修改其meta属性，添加如下内容：

1
type: "categories"

在本地调试后，即可发现categories页面跳转正常。

在文章写作过程中，可以在meta数据中添加categories字段，仅支持单个分类，如：

1
categories: Hexo

新建文章

站点基本配置完毕，我们可以开始写作自己的文章啦！

打开Git Bash，键入以下命令：

1
$ hexo new "title"

该命令会在Hexo/source/_post 目录下新建名为title.md的文件，打开该文件即可进行写作。

本地调试后，即可在网站中找到自己刚刚写作的文章。

文章草稿及发布

如果不想在部署时让自己还未写完的文章也被发布，即可通过以下命令新建草稿。

1
$ hexo new draft "title"

该命令会在Hexo/source/_draft 目录下新建名为title.md的文件，打开该文件即可进行写作。当本地调试或部署至服务器时，默认无法查找到草稿，即不会发布草稿文章。

在文章写作完毕后，需要将其移动至post文件夹，采用以下命令：

1
$ hexo publish "title"

该命令会将 Hexo/source/_draft 目录下对应的文章移动至 Hexo/source/_post 目录，再次本地调试或部署后即可找到该文章。

实用工具

数学公式的支持

Hexo采用的默认markdown渲染器对于复杂数学公式的支持不够完美，在渲染latex公式时会出现渲染错误，如将 _ 识别为markdown斜体标识，从而导致公式渲染失败。

**解决方案：**采用hexo-renderer-pandoc作为新的渲染器，该插件可以完美解决上述问题。

具体步骤：

  1. 由于hexo-renderer-pandoc需要Pandoc的支持，故需要先安装Pandoc，进入链接安装即可。这里选择windows-x86_64.msi的版本。

  2. 在Pandoc安装完毕后，回到Git Bash，键入以下命令：

    1
    $ pandoc -v

    若正确显示版本号即可进行下一步，若返回未找到该命令，则检查系统环境变量后重启电脑即可。

  3. 卸载默认的渲染器并安装对应插件。

    1
    2
    $ npm uninstall hexo-renderer-marked --save
    $ npm install hexo-renderer-pandoc --save

  4. 安装mathJax。

    1
    $ npm install hexo-filter-mathjax --save

  5. 进入站点配置文件，添加如下内容：

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    mathjax:
      tags: none # or 'ams' or 'all'
      single_dollars: true # enable single dollar signs as in-line math delimiters
      cjk_width: 0.9 # relative CJK char width
      normal_width: 0.6 # relative normal (monospace) width
      append_css: true # add CSS to pages rendered by MathJax
      every_page: false # 如果设置为true,默认每篇文章都会被mathjax渲染

    # hexo-renderer-pandoc (https://github.com/wzpan/hexo-renderer-pandoc)
    pandoc:
      extra:
        - toc: # will be passed as `--toc`. Note the colon，如果不需要自动生成目录无需添加此行
      extensions:
        - '+hard_line_breaks'
        - '+emoji'
        - '-implicit_figures'
      template:
         ./pandoc_template.html # 如果不需要自动生成目录无需添加此行
    # -----------------------------------------------------

    若上文中 every_page 字段设为false，则需在每篇文章的meta数据中添加 mathjax: true字段，即可开启公式渲染。

  6. 进入NexT主题配置文件(NexT安装请参照Hexo + Next深度美化指北)，并搜索 math 字段，修改如下：

    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: true
        # Available values: none | ams | all
        tags: none

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

  7. 回到Git Bash，执行以下命令：

    1
    2
    3
    $ hexo clean
    $ hexo g
    $ hexo s

    即可在本地看到公式被成功渲染。

    （公式的支持真的是个大坑，花了我半天时间查阅资料T_T）

结语

本文章实用工具篇仍会不断更新，敬请大家持续关注！有关问题可以在侧边栏的微信链接联系我。后续会发布Hexo + Next深度美化指北，干货满满，敬请关注！