使用Hexo框架时的种种问题和解决方法

2023年07月19日 1.6k 字大概 6 分钟

最近折腾博客时发现了Hexo框架默认配置的一些问题。默认的配置下因为部分功能缺失和Markdown渲染器问题会导致博客的实际呈现有错误。

本文中会记录一些笔者遇到的问题和解决方法。也许会更新......

[Hexo官方文档](https://hexo.io/docs/)
Markdown中使用LaTeX公式的渲染问题
在博客文章中添加Emoji表情

Hexo官方文档

Markdown中使用LaTeX公式的渲染问题

Hexo框架默认会使用hexo-renderer-marked来作为markdown的渲染器，然后再给默认安装的Mathjax来渲染公式。在该渲染方式下笔者文章中的所有公式都会被重复显示一遍。这似乎是这两个渲染器的转译规则导致了符号语法冲突。

网络上能够搜到的解决方案有很多，比如把原先的markdown渲染器修改为hexo-renderer-kramed，或者直接修改Mathjax的渲染引擎脚本。不过有些博客中提到hexo-renderer-kramed引擎需要改变一部分的文档语法，并且可能导致代码块高亮失效。而修改脚本又是麻烦事。因此笔者选择了一种较为简单的Pandoc渲染器+hexo-filter-mathjax公式插件的解决方案。其配置和安装都比较简单，解决了默认渲染器插件支持有限的问题，公式的编写语法也与大部分markdown编辑器一致。

更换渲染器

比Hexo默认渲染器更加好用的渲染器有不少，笔者选择的是hexo-renderer-pandoc(因为其兼容的语言较多)。除上文中提到的两种，在这里也推荐hexo-renderer-markdown-it，这个渲染器支持不少好用的插件。

步骤1: 卸载默认渲染器

开始安装前，我们先要移除原先的默认渲染器。在你的Hexo框架的blog根目录下打开终端，输入以下指令:

1	`npm uninstall hexo-renderer-marked --save`

步骤2: 安装新渲染器

同样在你的blog根目录下，安装pandoc渲染器:

1	`npm install hexo-renderer-pandoc --save`

如果要安装其他渲染器，那么直接将名称替换上面的hexo-renderer-pandoc即可。

步骤3:安装相关环境

对于Pandoc渲染器，这里直接安装Pandoc即可：Pandoc官网安装页面。具体安装方法根据自己的操作系统选择就行。

更换公式渲染插件

hexo-filter-mathjax这个公式插件是官方支持的插件之一，其支持的公式输入语法与主流markdown编辑器较为一致。

步骤1:卸载hexo-math

在你的Hexo框架的blog根目录下打开终端，输入以下指令:

1	`npm uninstall hexo-math --save`

步骤2:安装hexo-filter-mathjax

同样在你的blog根目录下，安装插件:

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

步骤3:在全局配置中配置公式渲染

在你的Hexo框架的blog根目录下打开_config.yml文件，在文件中加入如下内容:

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 # if true, every page will be rendered by MathJax regardless the `mathjax` setting in Front-matter

各个参数的用处可以看代码注释。没有特别需求基本不需要更改。

步骤4:需要公式的博客文章启用公式渲染器

在你写的，需要使用公式的markdown文档的front-matter中添加一个参数：

1	`mathjax: true`

以本片博客的front-matter为例:

---
title: 使用Hexo框架时的种种问题和解决方法
date: 2023-07-19 01:17:17
cover: https://cdn.jsdelivr.net/gh/KiRorY/pic_Warehouse/pic/post2/hexo.jpg
tags: 
- Hexo
categories: 教程
mathjax: true
---

如果你认为给单独一篇文章加参数太麻烦，你也可以在_config.yml文件中刚刚添加的mathjax设定下，把every_page的参数改为ture。

至此公式应该可以正常渲染，尝试以下矩阵式子是否能正常显示：

$$
\alpha=
\begin{pmatrix}
a & b & c \\
d & e & f \\
g & h & i 
\end{pmatrix} 
$$

渲染结果：

参考文档

[1] hexo博客next主题添加对数学公式的支持

[2] Hexo博客(13)添加MathJax数学公式渲染

[3] 在Hexo中使用Mathjax渲染数学公式

在博客文章中添加Emoji表情

markdown支持Emoji表情的使用，但是在Hexo框架下需要安装插件才能使表情能被渲染。在Markdown中使用公式的渲染问题中，笔者提到了hexo-renderer-markdown-it这个渲染器，如果你安装了该渲染器，那么可以直接安装渲染器插件markdown-it-emoji(不过通常该渲染器已经自带了这个插件了)。在你的Hexo框架blog根目录下打开终端，输入以下指令:

1	`npm install markdown-it-emoji --save`

笔者安装的渲染器是Pandoc,所以需要安装另一个插件hexo-filter-github-emojis，以下是该插件的安装和配置流程。

步骤1：安装插件

在Hexo框架blog根目录下打开终端，输入以下指令:

1	`npm install hexo-filter-github-emojis --save`

步骤2：在全局配置中启用插件

打开博客根目录下的_config.yml配置文件，添加以下语句:

githubEmojis:
  enable: true
  className: github-emoji
  unicode: true
  styles:
    display: inline
    vertical-align: middle # Freemind适用
  localEmojis:

关于参数的说明可以查看其Github说明文档。

在文章中插入Emoji表情 😃

Emoji的插入方法有很多，比较方便是直接使用Emoji的快捷代码。例如：:grinning: 😀 。Emoji表情的快捷代码可以直接上网找，这里提供一个Emoji快捷码对照网站。

参考文档

[1] Hexo 博客使用 emoji 表情