Common Issues and Fixes When Using Hexo

07/19/2023 1.3K words About 8 min

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

By default, the Hexo framework uses hexo-renderer-marked as the Markdown renderer, and then passes the output to the default MathJax installation to render formulas. Under this rendering method, all \(\LaTeX\) formulas in my posts were rendered twice. This seems to be due to conflicting syntax and escaping rules between the two renderers.

There are many solutions available online, such as replacing the default Markdown renderer with hexo-renderer-kramed, or directly modifying MathJax's rendering engine scripts. However, some blogs mention that the hexo-renderer-kramed engine requires altering some document syntax and may cause code block highlighting to break. Modifying scripts is also quite tedious. Therefore, I opted for a simpler solution: Pandoc renderer + hexo-filter-mathjax formula plugin. Its configuration and installation are straightforward, it solves the limited plugin support issue of the default renderer, and the formula writing syntax remains consistent with most Markdown editors.

Replacing the Renderer

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

Step 1: Uninstall the Default Renderer

Before installation, we need to remove the original default renderer. Open a terminal in the root directory of your Hexo blog and run the following command:

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

Step 2: Install the New Renderer

Also 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 hexo-renderer-pandoc above with its name.

Step 3: Install Required Dependencies

For the Pandoc renderer, you just need to install Pandoc directly: Pandoc Official Installation Page. Choose the installation method based on your operating system.

Replacing the Formula Rendering Plugin

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

Step 1: Uninstall hexo-math

Open a terminal in the root directory of your Hexo blog and run the following command:

1	`npm uninstall hexo-math --save`

Step 2: Install hexo-filter-mathjax

Also in your blog root directory, install the plugin:

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

Step 3: Configure Formula Rendering in the Global Configuration

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

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. Unless you have specific needs, no changes are typically necessary.

Step 4: Enable the Formula Renderer in Blog Posts That Require Formulas

Add a parameter to the Front-matter of your Markdown post where you need to use \(\LaTeX\) formulas:

1	`mathjax: true`

Taking the Front-matter of this post as an example:

---
title: Issues and Solutions When Using the Hexo Framework
date: 2023-07-19 01:17:17
cover: https://cdn.jsdelivr.net/gh/KiRorY/pic_Warehouse/pic/post2/hexo.jpg
tags: 
- Hexo
categories: Tutorial
mathjax: true
---

If you feel it is too tedious to add the parameter to each post individually, you can also change the every_page parameter to true under the mathjax settings you just added in _config.yml.

At this point, formulas should render properly. Try the following matrix expression to see if it displays correctly:

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

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

References

[1] Adding Math Formula Support to Next Theme in Hexo Blog

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

[3] Rendering Math Formulas with MathJax in Hexo

Adding Emojis to Blog Posts

Markdown supports emojis, but plugins are required under the Hexo framework to render them. In LaTeX Formula Rendering Issues in Markdown, I mentioned the hexo-renderer-markdown-it renderer. If you installed this renderer, you can directly install the renderer plugin markdown-it-emoji (though this renderer usually includes this plugin by default). Open a terminal in the root directory of your Hexo blog and run the following command:

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

Since I installed the Pandoc renderer, I needed to install another plugin, hexo-filter-github-emojis. Below is the installation and configuration process for this plugin.

Step 1: Install the Plugin

Open a terminal in the root directory of your Hexo blog and run the following command:

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

Step 2: Enable the Plugin in the Global Configuration

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

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

For parameter descriptions, refer to its GitHub documentation.

Inserting Emojis into Posts :smiley:

There are many ways to insert emojis; a convenient approach is to directly use emoji shortcodes, for example: :grinning: :grinning:. Emoji shortcodes can be found online; here is an Emoji Shortcodes Reference Site.

References

[1] Using Emojis in Hexo Blog