CONTENT MANAGEMENT

Mathematics in Markdown

New in 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 [passthrough 擴展]。passthrough 擴展會保留被分隔符包圍的原始 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
   }
}

上述設定會在每個頁面上啟用數學渲染，除非您在 front matter 中將 math 參數設置為 false。若要根據需要啟用數學渲染，請將網站設定中的 math 參數設為 false，並在 front matter 中將 math 參數設為 true。如 步驟 3 中所示，請在您的基礎模板中使用此參數。

若要禁用內嵌片段的 passthrough，請從配置中省略 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/npm/mathjax@3/es5/tex-chtml.js"></script>
<script>
  MathJax = {
    tex: {
      displayMath: [['\\[', '\\]'], ['$$', '$$']],  // 區塊顯示
      inlineMath: [['\\(', '\\)']]                  // 內嵌顯示
    }
  };
</script>

上述分隔符必須與您的網站設定中的分隔符匹配。

步驟 3

根據需要在基礎模板中有條件地調用部分模板。

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

上面的示範會在您將 front matter 中的 math 參數設為 true 時載入部分模板。如果您沒有設置 math 參數，條件語句將回退到您網站設定中的 math 參數。

步驟 4

在 Markdown 中使用 LaTeX 或 TeX 排版語法包含數學方程式和表達式。

content/math-examples.md
這是一個內嵌方程式 \(a^*=x-b^*\)。

以下是區塊方程式：

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

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

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

以下也是區塊方程式：

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

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

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

如果您在網站設定中將 math 參數設為 false，您必須在 front matter 中將 math 參數設為 true。例如：

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

內嵌分隔符

上面的配置、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/npm/katex@0.16.9/dist/katex.min.css" integrity="sha384-n8MVd4RsNIU0tAv4ct0nTaAbDJwPJzDEaqSD1odI+WdtXRGWt2kTvGFasHpSy3SV" crossorigin="anonymous">
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/katex.min.js" integrity="sha384-XjKyOOlGwcjNTAIQHIpgOno0Hl1YQqzUOEleOLALmuqehneUG+vnGctmUb0ZY0l8" crossorigin="anonymous"></script>
<script defer src="https://cdn.jsdelivr.net/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 增加化學支持，請啟用 mhchem 擴展，詳情請參見 KaTeX 文件。

延伸閱讀

Data sources Diagrams