在Hugo PaperMod主题中加入数学支持的最简方式

Hugo PaperMod主题加入数学支持最简法

原创已于 2022-12-26 19:10:10 修改 · 1.3k 阅读

1 ·

CC 4.0 BY-SA版权

文章标签：

#前端 #javascript #经验分享

于 2022-09-20 21:28:51 首次发布

本文介绍了如何在不修改Hugo PaperMod主题文件的情况下，为博客添加数学公式支持。通过创建自定义文件，引入Katex CDN，并在文章中使用特定语法，实现了MathJax的行内和块状显示功能，同时提到了可拓展性，如引入nutshell插件。

概述

在Hugo的PaperMod的主题中加入数学公式支持是很多人的刚需，在此主题下最好的文章是PaperMod开发者给出的Math Typesetting 。根据此篇博客内容，我们发现加入数学公式功能需要对theme文件夹进行修改，但大部分人可能都使用了git submodule引入的主题文件。这使我们几乎无法通过修改主题文件来增加这一功能。

本文主要讨论了在使用submodule情况下，不通过修改主题文件加入数学公式支持。

解决方案

在当前的写作仓库内创建layouts/partials/math.html文件，写入以下内容：

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.2/dist/katex.min.css" integrity="sha384-bYdxxUwYipFNohQlHt0bjN/LCpueqWz13HufFEV1SUatKs1cm4L6fFgCi1jT643X" crossorigin="anonymous">
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.2/dist/katex.min.js" integrity="sha384-Qsn9KnoKISj6dI8g7p1HBlNpVx0I8p1SvlwOldgi3IorMle61nQy4zEahWYtljaz" crossorigin="anonymous"></script>
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.2/dist/contrib/auto-render.min.js" integrity="sha384-+VBxd3r6XgURycqtZ117nYw44OOcIax56Z4dCRWbxyPt0Koah1uHoK0o4+/RRE05" crossorigin="anonymous"></script>
<script>
    document.addEventListener("DOMContentLoaded", function() {
        renderMathInElement(document.body, {
          // customised options
          // • auto-render specific keys, e.g.:
          delimiters: [
              {left: '$$', right: '$$', display: true},
              {left: '$', right: '$', display: false},
              {left: '\\(', right: '\\)', display: false},
              {left: '\\[', right: '\\]', display: true}
          ],
          // • rendering keys, e.g.:
          throwOnError : false
        });
    });
</script>

对于此文件中的内容，我参考了Katex 文档中给出的代码。此配置与mathjax的使用是一致的。当然对于css和script中的引用链接读者可以自行修改为其他CDN或自行部署以提高访客的阅读体验。

然后创建layouts/partials/extend_head.html文件，写入以下内容：

{{ if or .Params.math .Site.Params.math }}
{{ partial "math.html" . }}
{{ end }}

最终，我们会获得如下目录结构：
math Struct

读者可前往我的博客查看具体结构。

当我们确认某一篇博客需要加入数学公式支持时，我们需要在markdown文件键入以下内容:

---
title: 
date: 
tags: 
math: true
---

此实例中的title等变量需要读者自行补齐。

读者可以通过 $\vec{F}$ 实现 $\vec{F}$ 的行内显示的效果。

当然读者也可以通过以下代码:

x = \begin{cases}
   a &\text{if } b \\\
   c &\text{if } d
\end{cases}

实现如下块状显示的效果:
$\begin{cases} a &\text{if } b \\ c &\text{if } d \end{cases}$

注意由于hugo会对字符进行转译，我们不能使用\\进行换行而需要使用\\\。

关于katex支持的latex函数，读者可以自行参考function 文档和Support Table。

拓展

当我们在配置文件内写入enableInlineShortcodes: true后，这意味着我们几乎可以在博客文章内引入和运行一切javascript文件且不影响其他博客文章。这大大增加了PaperMod的可拓展性。下图展示了我在博客内引入nutshell插件的情况:

Hugo Nutshell

为达成此目的，我们只需要在博客头部加入以下代码:


{{< nutshell.inline >}}

<script src="https://cdn.jsdelivr.net/gh/ncase/nutshell@1.0.2/nutshell.js"></script>

{{</ nutshell.inline >}}

此处的{{< nutshell.inline >}}中的nutshell可以替换为其他字符。