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

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

2023年07月19日07/19/2023 1.3K 字1.4K words 大概 5 分钟About 8 min

最近折腾博客时发现了 Hexo 默认配置下的一些常见问题，包括 Markdown 渲染与功能插件导致的展示异常。

本文记录我实际遇到的问题与可行修复方案，重点覆盖公式渲染和 Emoji 支持。

While maintaining the blog, I found several common issues in Hexo's default setup, especially around Markdown rendering and missing plugin support.

This post records practical fixes I used, mainly for LaTeX rendering and Emoji support.

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文件，在文件中加入如下内容:

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

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

1
2
3
4
5
6
7
8
$$
\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配置文件，添加以下语句:

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

Recently, while working on my blog, I discovered some common issues with Hexo's default configuration, including abnormal display caused by Markdown rendering and functional plugins.

This article records the problems I encountered and feasible solutions, focusing on formula rendering and Emoji support.

While maintaining the blog, I found several common issues in Hexo's default setup, especially around Markdown rendering and missing plugin support.

This post records practical fixes I used, mainly for LaTeX rendering and Emoji support.

Hexo Official Documentation

LaTeX Formula Rendering Issues in Markdown

The Hexo framework defaults to using hexo-renderer-marked as the Markdown renderer, and then uses the default-installed Mathjax to render formulas. Under this rendering method, all \(\LaTeX\) formulas in my articles would be displayed twice. This seems to be due to symbol syntax conflicts caused by the translation rules of these two renderers.

There are many solutions available online, such as changing the original Markdown renderer to hexo-renderer-kramed, or directly modifying the Mathjax rendering engine script. However, some blogs mention that the hexo-renderer-kramed engine requires changing some document syntax and may cause code block highlighting to fail. Modifying scripts is also troublesome. Therefore, I chose a relatively simple solution: Pandoc renderer + hexo-filter-mathjax formula plugin. Its configuration and installation are relatively simple, it solves the problem of limited default renderer plugin support, and the formula writing syntax is consistent with most Markdown editors.

Changing the Renderer

There are many renderers better than Hexo's default. I chose hexo-renderer-pandoc (because it supports more languages). In addition to the two mentioned above, I also recommend hexo-renderer-markdown-it; this renderer supports many useful plugins.

Step 1: Uninstall the Default Renderer

Before starting the installation, we first need to remove the original default renderer. Open the terminal in your Hexo framework's blog root directory and enter the following command: 
1
 
npm uninstall hexo-renderer-marked  --save

Step 2: Install the New Renderer

Similarly, in your blog root directory, install the Pandoc renderer: 
1
 
npm install hexo-renderer-pandoc  --save

If you want to install another renderer, simply replace the name hexo-renderer-pandoc above.

For the Pandoc renderer, you can directly install Pandoc: Pandoc Official Installation Page. Just choose the specific installation method according to your operating system.

Changing the Formula Rendering Plugin

hexo-filter-mathjax this formula plugin is one of the officially supported plugins, and its supported formula input syntax is relatively consistent with mainstream Markdown editors.

Step 1: Uninstall hexo-math

Open the terminal in your Hexo framework's blog root directory and enter the following command: 
1
 
npm uninstall hexo-math --save

Step 2: Install hexo-filter-mathjax

Similarly, in your blog root directory, install the plugin: 
1
 
npm install hexo-filter-mathjax  --save

Step 3: Configure Formula Rendering in Global Settings

Open the _config.yml file in your Hexo framework's blog root directory and add the following content:

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

The purpose of each parameter can be seen in the code comments. You generally don't need to change them unless there are special requirements.

Step 4: Enable Formula Renderer for Blog Posts Requiring Formulas

In the front-matter of your Markdown document that requires \(\LaTeX\) formulas, add a parameter: 
1
 
mathjax: true
Taking this blog post's front-matter as an example: 
1
2
3
4
5
6
7
8
9
 
---
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
---

If you find it too troublesome to add parameters to individual articles, you can also change the every_page parameter to true under the mathjax setting you just added in the _config.yml file.

At this point, formulas should render correctly. Try checking if the following matrix expression displays normally: 
1
2
3
4
5
6
7
8
 
$$
\alpha=
\begin{pmatrix}
a & b & c \\
d & e & f \\
g & h & i 
\end{pmatrix} 
$$

Rendering result: \[ \alpha= \begin{pmatrix} a & b & c \\ d & e & f \\ g & h & i \end{pmatrix} \]

References

[1] hexo blog next theme add support for mathematical formulas

[2] Hexo Blog (13) Adding MathJax Math Formula Rendering

[3] Rendering MathJax Math Formulas in Hexo

Adding Emoji to Blog Posts

Markdown supports the use of Emoji, but under the Hexo framework, a plugin needs to be installed for emojis to be rendered. In LaTeX Formula Rendering Issues in Markdown, I mentioned the hexo-renderer-markdown-it renderer. If you have installed this renderer, you can directly install the renderer plugin markdown-it-emoji (though this renderer usually comes with it). Open the terminal in your Hexo framework's blog root directory and enter the following command: 
1
 
npm install markdown-it-emoji --save

The renderer I installed is Pandoc, so I need to install another plugin, hexo-filter-github-emojis. The installation and configuration process for this plugin is as follows.

Step 1: Install the Plugin

Open the terminal in your Hexo framework's blog root directory and enter the following command: 
1
 
npm install hexo-filter-github-emojis --save

Step 2: Enable the Plugin in Global Settings

Open the _config.yml configuration file in the blog root directory and add the following statements:

1
2
3
4
5
6
7
8
 
githubEmojis:
  enable: true
  className: github-emoji
  unicode: true
  styles:
    display: inline
    vertical-align: middle # Freemind适用
  localEmojis:

For explanations of the parameters, refer to its Github documentation.

Inserting Emoji in Articles :smiley:

There are many ways to insert Emoji, and a convenient one is to directly use Emoji shortcodes. For example: :grinning: :grinning: . Emoji shortcodes can be found online; here is an Emoji Shortcode Reference Website.

References

[1] Hexo blog uses emoji expressions

本文作者Author：KiRorY
本文链接Permalink：https://kirory.xyz/2023/07/19/Hexo框架博客关于输入公式和表情的问题/
版权声明：本文采用 CC BY-NC-SA 3.0 CN 协议进行许可License：This work is licensed under CC BY-NC-SA 3.0 CN
教程 Hexo