Hexo 如何在tranquilpeak主题中使用mermaid语句与Latex语句

作者: Jim Wang 公众号: 巴博萨船长

摘要：在使用Hexo管理博客文章时，如果使用的Hexo主题（比如tranquilpeak主题）不支持Latex与mermaid语法，这个问题该如何解决？Typora与Hexo对这两种语法的支持有什么差异？如果博客文章是在Typora上编辑，且文件中包含Latex与mermaid语句时，如何用最小的代价实现这些文章能够通过Hexo渲染并发布

Abstract: When using Hexo to manage blog posts, if the Hexo theme used (such as tranquilpeak theme) does not support Latex and mermaid syntax, how to solve this problem? What is the difference between Typora and Hexo’s support for these two syntaxes? If the blog post is edited on Typora and the file contains Latex and mermaid sentences, how can these posts be rendered and published by Hexo with the least cost?

作者: Jim Wang 公众号: 巴博萨船长

背景

本博客的文章都是使用Typora完成编辑的，Typora是一款Markdown编辑器，其集成了Mermaid库，可以方便地在文章中添加诸如流程图，甘特图，时序图与类图等图表。Typora对Latex也进行了很好的支持，也能够轻松实现在文章中添加数学公式。我们简单总结一下，Markdown中实现图表可以使用mermaid，Markdown中实现数学公式可以使用Latex语句。

本博客使用的是Hexo这款基于Node.js的静态框架，生成的静态页面托管在Github上，这就决定了Typora中支持的特征不一定在Hexo中完美支持，必然存在一些差异。默认情况下Hexo是不支持mermaid的，而Latex的数学公式。使用Hexo主题不同，对这两个功能的支持也不同。本博客使用的是Hexo的tranquilpeak主题，该主题就不支持mermaid与Latex，本文就讨论一下，如何在该主题中完成对这两个功能的支持。当然解决问题的方法千千万万，本文讨论的只是其中一种，其目的就是在遇到相似问题时提供一种思路而已。

支持Mermaid语法

一些比较流行的Hexo主题，有的已经在主题代码中实现了对Mermaid语法的支持，仅需要对主题配置文件_config.yml稍作修改，即可开启Hexo中博客Mardown文章对Marmaid语法支持。但如果使用Hexo的tranquilpeak主题，需要自己动手完成的就相对较多。Mermaid的语法支持可以在前端实现，前端实现离不开JavaScript代码，整体思路就是在主题页面模版文件中找到一合适位置，添加使用JavaScript一文件，即mermaid.min.js。

Markdown文章中，Mermaid语法样式如下：

<pre class="mermaid">graph TD;
	A-->B;
	A-->C;
	B-->D;
	C-->D;
</pre>

Typora中输入上述内容就可以的到如下一个图表：

而下面的图片是由前端在页面加载时根据mermaid语句渲染而的，也是本文中，我们需要实现的目标。如果渲染不成功看到的即为文本，请注意两者差异：

graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;

如果Hexo不支持Mermaid语法，则生产的静态页面显示的还是文本，不是图表。检查页面元素发现，静态页面中的内容如下：

<pre class="mermaid">graph TD;
    A--&gt;B;
    A--&gt;C;
    B--&gt;D;
    C--&gt;D;</pre>

本章节开头就写到，可以在前端实现对mermaid语法的支持，也就是说要想办法使用将类class为mermaid元素转换成图表。实现这一目的，我们就需要添加插件支持，在Hexo目录下运行如下命令安装所需插件：

1	$ npm install --save hexo-filter-mermaid-diagrams

插件安装完成之后，需要对主题（本例使用tranquilpeak主题）配置文件_config.yml文件做少许修改，在配置文件末尾，添加如下内容：

# Mermaid (markdwon to flow chart, seq chart, class chart ...)
mermaid:
  enable: true
  # Available themes: default | dark | forest | neutral
  theme: default

接下来要做的是，搜索并下载最新版本（截至2020-12-19，版本为8.8.4）mermaid.min.js与mermaid.min.js.map的这两个文件。将文件保存在当前主题的/source/assets/js目录下。

然后就是在主题中添加代码使用这个js文件，插件Github首页建议的是修改after-footer.ejs, tranquilpeak主题没有此文件，themes/tranquilpeak/layout/_partial/script.ejs可以作为替代方案，在该文件中做出如下修改：

    .....  
	</script>
  <% } else if (theme.mermaid.enable) { %>  // 修改 开始位置
    <%- js('assets/js/mermaid.min.js') %>  // 或者使用CDN
    <script>
        $(document).ready(function() {
            var mermaid_config = {
                startOnLoad: true,
                theme: '<%- theme.mermaid.theme %>',
                flowchart:{
                    useMaxWidth: false,
                    htmlLabels: true
                }                
            }
            mermaid.initialize(mermaid_config);
        });
    </script>   // 修改 结束位置
  <% } else if (theme.gitalk.enable) { %>
....

我在示例代码中保留部分原有代码，以便各位更好定位所需添加代码在原文中的位置，代码第3行与第9行，就是我们在主题配置文件中添加的相关配置项。如果想使用CDN而不是本地文件，也可以对第4行进行修改或者结合配置文件，通过配置实现CDN与本地文件的切换。

完成上述内容基本上就完成了Hexo tranquilpeak主题对mermaid语法的支持配置。

支持Latex语法

Hexo 一些比较流行主题也在主题代码中完成了Latex语法的支持，遗憾的是Hexo tranquilpeak主题却没有，所以还需手动完成对Latex语法的支持。Hexo 对Latex语法的支持可以在后端实现。这里需要注意的是，由于Hexo 是静态博客框架，所以博客文章都是静态页面，没有真正意义上的后端服务器，这里所谓的后端完成，其实是在Hexo将Markdown渲染成html文件这个过程。

要实现Latex语法支持，就需要用到hexo-filter-mathjax这个Hexo插件，使用这个插件的时候需要注意，该插件不需要任何前端脚本与其他Math相关插件的支持，因此，若之前已经尝试了别的Math相关插件，或者前端脚本，请先卸载这些插件并移除相关前端脚本。在Hexo目录下运行如下命令安装所需插件：

1 2	$ npm install hexo-filter-mathjax $ hexo clean

安装完该插件后，就需要对Hexo配置文件进行必要修改适配。请注意不是Hexo主题配置文件，是Hexo项目配置文件_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

该插件的使用方法比较简单，仅需要在文章的预定义部分添加mathjax: true，这个控制项即可，示例如下：

---
title: On the Electrodynamics of Moving Bodies
categories: Physics
date: 1905-06-30 12:00:00
mathjax: true
---

插件Github首页推荐使用hexo-renderer-pandoc替代默认的hexo-renderer-marked，说是pandoc渲染插件相比默认的marked插件能够更好的处理Markdown文章中的数学公式，默认的渲染插件无法处理Latex与Markdown的语法冲突。由于截止目前我在使用marked渲染插件时还没遇到这样的通途，所以也就没尝试这个新的渲染插件，如果以后遇见，就在新的文章中讨论分享。

如果完成上述支持的配置就可以进行测试了，我们以如下Latex语句为例进行测试：

1
2
3

$$
i\hbar\frac{\partial}{\partial t}\psi=-\frac{\hbar^2}{2m}\nabla^2\psi+V\psi
$$

上述语句在Typora中会生成如下公式（注意下列公式为图片）：

下列公式，为插件渲染后公式，

其在渲染生成的HTML文件中为一SVG图形，HTML相关代码如下：

<mjx-container class="MathJax" jax="SVG" display="true">
  <svg style="vertical-align: -1.602ex" xmlns="http://www.w3.org/2000/svg" width="25.757ex" height="5.018ex" role="img" focusable="false" viewBox="0 -1509.9 11384.6 2217.9">
    ......
  </svg>
</mjx-container>

考虑到文章篇幅，svg元素中的内容在此省略。

小结

以上就是，在使用Hexo tranquilpeak主题时，如何在Hexo博客中实现Latex语法与mermaid语法的支持的所有内容。在使用Hexo一些主题时，可能不需要自己做这些配置。但是如果你使用的主题没有对这两项内容进行支持，就可以参考上述内容，独自完成Latex语法与mermaid语法的支持。能有此文全因自己好奇。在文章最后想说一下，这里没有专家，记录这些主要是为了自己以后回顾学习之方便，文章有不足之处也实属正常。见解不同，诚切赐教，关注微信公众号，一起讨论学习。