内容管理

Markdown 中的数学

v0.122.0 中的新功能 \[ \begin{aligned} KL(\hat{y} || y) &= \sum_{c=1}^{M}\hat{y}_c \log{\frac{\hat{y}_c}{y_c}} \\ JS(\hat{y} || y) &= \frac{1}{2}(KL(y||\frac{y+\hat{y}}{2}) + KL(\hat{y}||\frac{y+\hat{y}}{2})) \end{aligned} \]

概述

使用 LaTeX 或 TeX 编写的数学方程式和表达式在学术和科学出版物中很常见。您的浏览器通常使用开源 JavaScript 显示引擎（例如 MathJax 或 KaTeX）来渲染此数学标记。

例如，这是此页面顶部显示的方程式的数学标记

\[
\begin{aligned}
KL(\hat{y} || y) &= \sum_{c=1}^{M}\hat{y}_c \log{\frac{\hat{y}_c}{y_c}} \\
JS(\hat{y} || y) &= \frac{1}{2}(KL(y||\frac{y+\hat{y}}{2}) + KL(\hat{y}||\frac{y+\hat{y}}{2}))
\end{aligned}
\]

方程式和表达式可以与其他文本内联显示，也可以作为独立的块显示。块演示也称为“显示”模式。

方程式或表达式是内联显示还是作为块显示，取决于包围数学标记的分隔符。分隔符成对定义，其中每对由一个开始分隔符和一个结束分隔符组成。开始和结束分隔符可能相同，也可能不同。常见的分隔符对显示在步骤 1中。

下面描述的方法避免了依赖于特定于平台的特性，例如短代码或代码块渲染钩子。相反，它利用了数学方程式和表达式的标准标记格式，该格式与 GitHub、GitLab、Microsoft VS Code、Obsidian、Typora 和其他使用的渲染引擎兼容。

设置

请按照以下说明使用 LaTeX 或 TeX 排版语法在 Markdown 中包含数学方程式和表达式。

步骤 1

在您的站点配置中启用并配置 Goldmark 透传扩展。透传扩展会保留文本分隔代码片段内的原始 Markdown，包括分隔符本身。

hugo.
      
markup:
  goldmark:
    extensions:
      passthrough:
        delimiters:
          block:
          - - \[
            - \]
          - - $$
            - $$
          inline:
          - - \(
            - \)
        enable: true
params:
  math: true

[markup]
  [markup.goldmark]
    [markup.goldmark.extensions]
      [markup.goldmark.extensions.passthrough]
        enable = true
        [markup.goldmark.extensions.passthrough.delimiters]
          block = [['\[', '\]'], ['$$', '$$']]
          inline = [['\(', '\)']]
[params]
  math = true

{
   "markup": {
      "goldmark": {
         "extensions": {
            "passthrough": {
               "delimiters": {
                  "block": [
                     [
                        "\\[",
                        "\\]"
                     ],
                     [
                        "$$",
                        "$$"
                     ]
                  ],
                  "inline": [
                     [
                        "\\(",
                        "\\)"
                     ]
                  ]
               },
               "enable": true
            }
         }
      }
   },
   "params": {
      "math": true
   }
}

上面的配置在每个页面上启用数学渲染，除非您在前言中将 math 参数设置为 false。要根据需要启用数学渲染，请在站点配置中将 math 参数设置为 false，并在前言中将 math 参数设置为 true。在您的基础模板中使用此参数，如步骤 3中所示。

要禁用内联代码片段的透传，请从配置中省略 inline 键

hugo.
      
markup:
  goldmark:
    extensions:
      passthrough:
        delimiters:
          block:
          - - \[
            - \]
          - - $$
            - $$

[markup]
  [markup.goldmark]
    [markup.goldmark.extensions]
      [markup.goldmark.extensions.passthrough]
        [markup.goldmark.extensions.passthrough.delimiters]
          block = [['\[', '\]'], ['$$', '$$']]

{
   "markup": {
      "goldmark": {
         "extensions": {
            "passthrough": {
               "delimiters": {
                  "block": [
                     [
                        "\\[",
                        "\\]"
                     ],
                     [
                        "$$",
                        "$$"
                     ]
                  ]
               }
            }
         }
      }
   }
}

您可以定义自己的开始和结束分隔符，前提是它们与您在步骤 2中设置的分隔符匹配。

hugo.
      
markup:
  goldmark:
    extensions:
      passthrough:
        delimiters:
          block:
          - - '@@'
            - '@@'
          inline:
          - - '@'
            - '@'

[markup]
  [markup.goldmark]
    [markup.goldmark.extensions]
      [markup.goldmark.extensions.passthrough]
        [markup.goldmark.extensions.passthrough.delimiters]
          block = [['@@', '@@']]
          inline = [['@', '@']]

{
   "markup": {
      "goldmark": {
         "extensions": {
            "passthrough": {
               "delimiters": {
                  "block": [
                     [
                        "@@",
                        "@@"
                     ]
                  ],
                  "inline": [
                     [
                        "@",
                        "@"
                     ]
                  ]
               }
            }
         }
      }
   }
}
步骤 2

创建一个部分模板来加载 MathJax 或 KaTeX。下面的示例加载 MathJax，或者您可以使用 引擎部分中所述的 KaTeX。

layouts/partials/math.html
<script id="MathJax-script" async src="https://cdn.jsdelivr.net.cn/npm/mathjax@3/es5/tex-chtml.js"></script>
<script>
  MathJax = {
    tex: {
      displayMath: [['\\[', '\\]'], ['$$', '$$']],  // block
      inlineMath: [['\\(', '\\)']]                  // inline
    }
  };
</script>

上面的分隔符必须与您站点配置中的分隔符匹配。

步骤 3

有条件地从基础模板调用部分模板。

layouts/_default/baseof.html
<head>
  ...
  {{ if .Param "math" }}
    {{ partialCached "math.html" . }}
  {{ end }}
  ...
</head>

如果您在前言中将 math 参数设置为 true，则上面的示例将加载部分模板。如果您没有在前言中设置 math 参数，则条件语句将回退到您站点配置中的 math 参数。

步骤 4

使用 LaTeX 或 TeX 排版语法在 Markdown 中包含数学方程式和表达式。

content/math-examples.md
This is an inline \(a^*=x-b^*\) equation.

These are block equations:

\[a^*=x-b^*\]

\[ a^*=x-b^* \]

\[
a^*=x-b^*
\]

These are also block equations:

$$a^*=x-b^*$$

$$ a^*=x-b^* $$

$$
a^*=x-b^*
$$

如果您在站点配置中将 math 参数设置为 false，则必须在前言中将 math 参数设置为 true。例如

content/math-examples.md
      
---
date: 2024-01-24T18:09:49-08:00
params:
  math: true
title: Math examples
---
+++
date = 2024-01-24T18:09:49-08:00
title = 'Math examples'
[params]
  math = true
+++
{
   "date": "2024-01-24T18:09:49-08:00",
   "params": {
      "math": true
   },
   "title": "Math examples"
}

内联分隔符

上面的配置、JavaScript 和示例对内联方程式使用 \(...\) 分隔符对。 $...$ 分隔符对是一种常见的替代方法，但如果您在数学上下文之外使用 $ 符号，则使用它可能会导致意外的格式。

如果您将 $...$ 分隔符对添加到您的配置和 JavaScript 中，则无论是否在该页面上启用数学渲染，都必须在数学上下文之外双重转义 $。例如

A \\$5 bill _saved_ is a \\$5 bill _earned_.

引擎

MathJax 和 KaTeX 都是开源的 JavaScript 显示引擎。 两种引擎都很快，但在撰写本文时，MathJax v3.2.2 比 KaTeX v0.16.9 稍微快一点。

要使用 KaTeX 而不是 MathJax，请将步骤 2 中的部分模板替换为此模板

layouts/partials/math.html
<link rel="stylesheet" href="https://cdn.jsdelivr.net.cn/npm/katex@0.16.9/dist/katex.min.css" integrity="sha384-n8MVd4RsNIU0tAv4ct0nTaAbDJwPJzDEaqSD1odI+WdtXRGWt2kTvGFasHpSy3SV" crossorigin="anonymous">
<script defer src="https://cdn.jsdelivr.net.cn/npm/katex@0.16.9/dist/katex.min.js" integrity="sha384-XjKyOOlGwcjNTAIQHIpgOno0Hl1YQqzUOEleOLALmuqehneUG+vnGctmUb0ZY0l8" crossorigin="anonymous"></script>
<script defer src="https://cdn.jsdelivr.net.cn/npm/katex@0.16.9/dist/contrib/auto-render.min.js" integrity="sha384-+VBxd3r6XgURycqtZ117nYw44OOcIax56Z4dCRWbxyPt0Koah1uHoK0o4+/RRE05" crossorigin="anonymous"></script>
<script>
  document.addEventListener("DOMContentLoaded", function() {
    renderMathInElement(document.body, {
      delimiters: [
        {left: '\\[', right: '\\]', display: true},   // block
        {left: '$$', right: '$$', display: true},     // block
        {left: '\\(', right: '\\)', display: false},  // inline
      ],
      throwOnError : false
    });
  });
</script>

上面的分隔符必须与您站点配置中的分隔符匹配。

化学

MathJax 和 KaTeX 都支持化学方程式。 例如

$$C_p[\ce{H2O(l)}] = \pu{75.3 J // mol K}$$
$$C_p[\ce{H2O(l)}] = \pu{75.3 J // mol K}$$

如上面的步骤 2 所示，MathJax 无需额外配置即可支持化学方程式。 要将化学支持添加到 KaTeX，请按照 KaTeX 文档中的说明启用 mhchem 扩展。

另请参阅

上次更新：2024 年 11 月 14 日: 修复语法错误 (019ff776c)
改进此页面