图表和公式

Docsy内置了对许多图表创建和排版工具的支持，您可以使用这些工具向网站添加丰富的内容，包括（KaTeX），Mermaid，Diagrams.net，PlantUML和MarkMap。

\(\LaTeX\) 支持 \(\KaTeX\)

\(\LaTeX\) 是用于制作技术和科学文献的高质量排版系统。由于其出色的数学排版能力, \(\TeX\) 成为科学文件交流和出版的事实标准，特别是如果这些文件包含大量数学公式。最初版本由唐纳德·克努斯（Donald Knuth）设计和编写，于1978年发布。追溯到那么远， \(\LaTeX\) 将“pdf”作为其主要输出目标，并且不是特别适合为 Web 生成 HTML 输出。幸运的是，有了 \(\KaTeX\) 网络上有一个快速且易于使用的 JavaScript 库，用于 \(\TeX\) 数学渲染，该库已集成到 Docsy 主题中。

借助 Docsy 中的 \(\KaTeX\) 支持 [enabled]（#activating-and-configuring-katex-support），您可以将复杂的数学公式包含在您的网页中，无论是内联的还是以自己的行为中心的。由于 \(\KaTeX\) 依赖于服务器端渲染，因此无论您的浏览器或环境如何，它都会生成相同的输出。公式可以内联显示，也可以显示模式：

内联公式

下面的代码示例生成一个包含三个内联公式的文本行：

When \\(a \ne 0\\), there are two solutions to \\(ax^2 + bx + c= 0\\) and they are \\(x = {-b \pm \sqrt{b^2-4ac} \over 2a}\\).

When \(a \ne 0\), there are two solutions to \(ax^2 + bx + c= 0\) and they are \(x = {-b \pm \sqrt{b^2-4ac} \over 2a}\).

显示模式下的公式

下面的代码示例生成一个介绍性文本行，后跟一个编号为“（1）”的公式，该公式位于其自己的行上：

The probability of getting \\(k\\) heads when flipping \\(n\\) coins is:
```math
\tag*{(1)} P(E) = {n \choose k} p^k (1-p)^{n-k}
```

公式本身写在 [GLFM 数学块]（https://docs.gitlab.com/ee/user/markdown.html#math） 中。上面的代码片段呈现为：

掷硬币时得到 \(k\) 个正面的概率为：

$$
\tag*{(1)} P(E) = {n \choose k} p^k (1-p)^{n-k}
$$

激活和配置 \(\KaTeX\) 支持

自动激活

只要您在页面上使用“math”代码块，就会自动启用对 \(\KaTeX\) 的支持。

手动激活（不存在“math”代码块或 hugo 0.92 或更低）

如果您想使用内联公式，并且页面中没有触发自动激活的“数学”代码块，则需要手动激活 \(\KaTeX\) 支持。最简单的方法是在页面的首页添加一个“math”属性，并将其设置为“true”：

• Page front matter:
• toml
• yaml
• json

+++
math = true
+++

---
math: true
---

{
  "math": true
}

如果你在大多数页面中使用公式，你还可以在Docsy主题中启用全站的 \(\KaTeX\) 支持。为此，请更新 ‘hugo.toml’/‘hugo.yaml’/‘hugo.json’：

• Site configuration file:
• hugo.toml
• hugo.yaml
• hugo.json

[params.katex]
enable = true

params:
  katex:
    enable: true

{
  "params": {
    "katex": {
      "enable": true
    }
  }
}

此外，如果需要，您可以在 ‘hugo.toml’/‘hugo.yaml’/‘hugo.json’ 中自定义各种 \(\KaTeX\) 选项：

• Site configuration file:
• hugo.toml
• hugo.yaml
• hugo.json

[params.katex]
# enable/disable KaTeX support
enable = true
# Element(s) scanned by auto render extension. Default: document.body
html_dom_element = "document.body"

[params.katex.options]
# If true (the default), KaTeX will throw a ParseError when it encounters an
# unsupported command or invalid LaTeX. If false, KaTeX will render unsupported
# commands as text, and render invalid LaTeX as its source code with hover text
# giving the error, in the color given by errorColor.
throwOnError = false
errorColor = "#CD5C5C"

# This is a list of delimiters to look for math, processed in the same order as
# the list. Each delimiter has three properties:
#   left:    A string which starts the math expression (i.e. the left delimiter).
#   right:   A string which ends the math expression (i.e. the right delimiter).
#   display: Whether math in the expression should be rendered in display mode.
[[params.katex.options.delimiters]]
  left = "$$"
  right = "$$"
  display = true
[[params.katex.options.delimiters]]
  left = "$"
  right = "$"
  display = false
[[params.katex.options.delimiters]]
  left = "\\("
  right = "\\)"
  display = false
[[params.katex.options.delimiters]]
  left = "\\["
  right = "\\]"
  display = true

params:
  katex:
    enable: true  # enable/disable KaTeX support
    html_dom_element: document.body  # Element(s) scanned by auto render extension. Default: document.body
    options:

      # If true (the default), KaTeX will throw a ParseError when it encounters an
      # unsupported command or invalid LaTeX. If false, KaTeX will render unsupported
      # commands as text, and render invalid LaTeX as its source code with hover text
      # giving the error, in the color given by errorColor.
      throwOnError: false
      errorColor: '#CD5C5C'

      # This is a list of delimiters to look for math, processed in the same order as
      # the list. Each delimiter has three properties:
      #   left:    A string which starts the math expression (i.e. the left delimiter).
      #   right:   A string which ends the math expression (i.e. the right delimiter).
      #   display: Whether math in the expression should be rendered in display mode.
      delimiters:
        - left: $$
          right: $$
          display: true
        - left: $
          right: $
          display: false
        - left: \(
          right: \)
          display: false
        - left: \[
          right: \]
          display: true

{
  "params": {
    "katex": {
      "enable": true,
      "html_dom_element": "document.body",
      "options": {
        "throwOnError": false,
        "errorColor": "#CD5C5C",
        "delimiters": [
          {
            "left": "$$",
            "right": "$$",
            "display": true
          },
          {
            "left": "$",
            "right": "$",
            "display": false
          },
          {
            "left": "\\(",
            "right": "\\)",
            "display": false
          },
          {
            "left": "\\[",
            "right": "\\]",
            "display": true
          }
        ]
      }
    }
  }
}

有关选项的完整列表及其详细说明，请查看 \({\KaTeX}\) 的 [Rendering API options]（https://katex.org/docs/autorender.html#api） 和 \({\KaTeX}\) 的 [configuration options]（https://katex.org/docs/options.html） 的文档。

显示化学方程式和物理单位

[mhchem]（https://www.ctan.org/pkg/mhchem） 是一个 \(\LaTeX\) 包，用于排版化学分子式和方程式。幸运的是，\(\KaTeX\) 提供了 ‘mhchem’ [extension]（https://github.com/KaTeX/KaTeX/tree/main/contrib/mhchem），使 ‘mhchem’ 包在为 Web 创作内容时可以访问。使用“mhchem”扩展 [enabled]（#activating-rendering-support-for-chemical-formulae），您可以轻松地将化学方程式包含在您的页面中。方程可以内联显示，也可以驻留在自己的行上。下面的代码示例生成一个包含化学方程式的文本行：

*Precipitation of barium sulfate:* \\(\ce{SO4^2- + Ba^2+ -> BaSO4 v}\\)

Precipitation of barium sulfate: \(\ce{SO4^2- + Ba^2+ -> BaSO4 v}\)

更复杂的方程需要显示在自己的行上。使用装饰有“chem”的代码块来实现这一点：

```chem
\tag*{(2)} \ce{Zn^2+  <=>[+ 2OH-][+ 2H+]  $\underset{\text{amphoteric hydroxide}}{\ce{Zn(OH)2 v}}$  <=>[+ 2OH-][+ 2H+]  $\underset{\text{tetrahydroxozincate}}{\ce{[Zn(OH)4]^2-}}$}
```

$$
\tag*{(2)} \ce{Zn^2+  <=>[+ 2OH-][+ 2H+]  $\underset{\text{amphoteric hydroxide}}{\ce{Zn(OH)2 v}}$  <=>[+ 2OH-][+ 2H+]  $\underset{\text{tetrahydroxozincate}}{\ce{[Zn(OH)4]^2-}}$}
$$

mhchem 的使用不仅限于编写化学方程式，使用包含的 \pu命令，也可以轻松编写漂亮的物理单位。下面的代码示例生成两个文本行，其中包含四个数字及其对应的物理单位：

* Scientific number notation: \\(\pu{1.2e3 kJ}\\) or \\(\pu{1.2E3 kJ}\\) \\
* Divisions: \\(\pu{123 kJ/mol}\\) or \\(\pu{123 kJ//mol}\\)

• Scientific number notation: \(\pu{1.2e3 kJ}\) or \(\pu{1.2E3 kJ}\)
• Divisions: \(\pu{123 kJ/mol}\) or \(\pu{123 kJ//mol}\)

有关创作物理单位时的完整选项列表，请查看“mhchem”文档中关于物理单位的 [section]（https://mhchem.github.io/MathJax-mhchem/#pu）。

激活对化学式的渲染支持

自动激活

只要您在页面上使用“chem”代码块，就会自动启用对化学方程式的渲染支持。

手动激活（不存在“化学”代码块或 hugo 0.92 或更低）

如果要内联使用化学式，并且页面中没有触发自动激活的“chem”代码块，则需要手动激活对化学式呈现支持。最简单的方法是在页面的 frontmatter 中添加一个 ‘chem’ 属性，并将其设置为 ’true’：

• Page front matter:
• toml
• yaml
• json

+++
chem = true
+++

---
chem: true
---

{
  "chem": true
}

如果您在大多数页面中使用公式，您还可以在 Docsy 主题中启用对化学公式的全站渲染支持。为此，请在“hugo.toml”/“hugo.yaml”/“hugo.json”中启用“mhchem”：

• Site configuration file:
• hugo.toml
• hugo.yaml
• hugo.json

[params.katex]
enable = true

[params.katex.mhchem]
enable = true

params:
  katex:
    enable: true
    mhchem:
      enable: true

{
  "params": {
    "katex": {
      "enable": true,
      "mhchem": {
        "enable": true
      }
    }
  }
}

美人鱼图

[美人鱼]（https://mermaid-js.github.io） 是一个 Javascript 库，用于在浏览器中将简单的文本定义呈现为有用的图表。 它可以生成各种不同的图表类型，包括流程图、序列图、类图、状态图、ER 图、用户旅程图、甘特图和饼图。

在 Docsy 中启用 Mermaid 支持后，您可以在代码块中包含 Mermaid 图表的文本定义，并且浏览器将在页面加载后立即自动呈现它。

这样做的最大好处是，任何可以编辑页面的人现在都可以编辑图表 - 不再需要寻找原始工具和版本来进行新的编辑。

例如，下面定义了一个序列图：

```mermaid
sequenceDiagram
    autonumber
    Docsy user->>Discussion board: Ask question
    Discussion board->>Community member: read question
    loop Different strategies
    Community member->>Test instance: Investigate issue raised
    end
    Note right of Community member: After hours of investigation:
    Test instance-->>Community member: Come up with solution
    Community member-->>Discussion board: Propose solution
    Discussion board-->>Docsy user: check proposed solution
    Docsy user->>Discussion board: Mark question as resolved
    Docsy user->>Docsy user: Being happy
```

它会自动呈现为：

sequenceDiagram
    autonumber
    Docsy user->>Discussion board: Ask question
    Discussion board->>Community member: read question
    loop Different strategies
    Community member->>Test instance: Investigate issue raised
    end
    Note right of Community member: After hours of investigation:
    Test instance-->>Community member: Come up with solution
    Community member-->>Discussion board: Propose solution
    Discussion board-->>Docsy user: check proposed solution
    Docsy user->>Discussion board: Mark question as resolved
    Docsy user->>Docsy user: Being happy

一旦您在页面上使用“美人鱼”代码块，就会自动启用对美人鱼图的支持。

默认情况下，docsy 会在构建时拉入最新的官方发布的 Mermaid 版本。如果这不符合您的需求，您可以在配置文件 ‘hugo.toml’/‘hugo.yaml’/‘hugo.json’ 中指定通缉的美人鱼版本：

• Configuration file:
• hugo.toml
• hugo.yaml
• hugo.json

[params.mermaid]
version = "10.9.0"

params:
  mermaid:
    version: 10.9.0

{
  "params": {
    "mermaid": {
      "version": "10.9.0"
    }
  }
}

如果需要，您可以为图表定义自定义设置，例如主题，在“hugo.toml”/“hugo.yaml”/“hugo.json”中填充。

• Configuration file:
• hugo.toml
• hugo.yaml
• hugo.json

[params.mermaid]
theme = "neutral"

[params.mermaid.flowchart]
diagramPadding = 6

params:
  mermaid:
    theme: neutral
    flowchart:
      diagramPadding: 6

{
  "params": {
    "mermaid": {
      "theme": "neutral",
      "flowchart": {
        "diagramPadding": 6
      }
    }
  }
}

请参阅 [Mermaid 文档]（https://mermaid-js.github.io/mermaid/#/Setup?id=mermaidapi-configuration-defaults） 了解可覆盖的默认值列表。

还可以通过在逻辑示意图定义的开头使用 [frontmatter config]（http://mermaid.js.org/config/theming.html#customizing-themes-with-themevariables） 块来覆盖每个逻辑示意图的设置。

带有PlantUML的UML图

[植物UML]（https://plantuml.com/en/） 是 Mermaid 的替代品，可让您快速创建 UML 图，包括序列图、用例图和状态图。与完全在浏览器中呈现的美人鱼图不同，PlantUML 使用 PlantUML 服务器来创建图。您可以使用提供的默认演示服务器（不建议用于生产用途），也可以自行运行服务器。PlantUML 提供的图像类型比 Mermaid 更广泛，因此对于某些用例来说可能是更好的选择。

图表是使用简单直观的语言定义的。（[参见 PlantUML 语言参考指南]（https://plantuml.com/en/guide））。

以下示例显示了一个用例图：

```plantuml
participant participant as Foo
actor       actor       as Foo1
boundary    boundary    as Foo2
control     control     as Foo3
entity      entity      as Foo4
database    database    as Foo5
collections collections as Foo6
queue       queue       as Foo7
Foo -> Foo1 : To actor
Foo -> Foo2 : To boundary
Foo -> Foo3 : To control
Foo -> Foo4 : To entity
Foo -> Foo5 : To database
Foo -> Foo6 : To collections
Foo -> Foo7: To queue
```

自动呈现为：

participant participant as Foo
actor       actor       as Foo1
boundary    boundary    as Foo2
control     control     as Foo3
entity      entity      as Foo4
database    database    as Foo5
collections collections as Foo6
queue       queue       as Foo7
Foo -> Foo1 : To actor
Foo -> Foo2 : To boundary
Foo -> Foo3 : To control
Foo -> Foo4 : To entity
Foo -> Foo5 : To database
Foo -> Foo6 : To collections
Foo -> Foo7: To queue

要启用/禁用 PlantUML，请更新 ‘hugo.toml’/‘hugo.yaml’/‘hugo.json’：

• Configuration file:
• hugo.toml
• hugo.yaml
• hugo.json

[params.plantuml]
enable = true

params:
  plantuml:
    enable: true

{
  "params": {
    "plantuml": {
      "enable": true
    }
  }
}

其他可选设置包括：

• Configuration file:
• hugo.toml
• hugo.yaml
• hugo.json

[params.plantuml]
enable = true
theme = "default"

# Set url to plantuml server
# default is http://www.plantuml.com/plantuml/svg/
svg_image_url = "https://www.plantuml.com/plantuml/svg/"

# By default the plantuml implementation uses <img /> tags to display UML diagrams.
# When svg is set to true, diagrams are displayed using <svg /> tags, maintaining functionality like links e.g.
# default = false
svg = true

params:
  plantuml:
    enable: true
    theme: default
    # Set url to plantuml server
    # default is http://www.plantuml.com/plantuml/svg/
    svg_image_url: 'https://www.plantuml.com/plantuml/svg/'
    # By default the plantuml implementation uses <img /> tags to display UML diagrams.
    # When svg is set to true, diagrams are displayed using <svg /> tags, maintaining functionality like links e.g.
    # default = false
    svg: true

{
  "params": {
    "plantuml": {
      "enable": true,
      "theme": "default",
      "svg_image_url": "https://www.plantuml.com/plantuml/svg/",
      "svg": true
    }
  }
}

MarkMap 支持 MindMap

[标记地图]（https://markmap.js.org/） 是一个 Javascript 库，用于在浏览器中将简单的文本定义呈现给思维导图。

例如，下面定义了一个简单的思维导图：

```markmap
# markmap

## Links

- <https://markmap.js.org/>
- [GitHub](https://github.com/gera2ld/markmap)

## Related

- [coc-markmap](https://github.com/gera2ld/coc-markmap)
- [gatsby-remark-markmap](https://github.com/gera2ld/gatsby-remark-markmap)

## Features

- links
- **inline** ~~text~~ *styles*
- multiline
  text
- `inline code`
-
    ```js
    console.log('code block');
    ```
- Katex - $x = {-b \pm \sqrt{b^2-4ac} \over 2a}$
```

自动呈现为：

# markmap

## Links

- <https://markmap.js.org/>
- [GitHub](https://github.com/gera2ld/markmap)

## Related

- [coc-markmap](https://github.com/gera2ld/coc-markmap)
- [gatsby-remark-markmap](https://github.com/gera2ld/gatsby-remark-markmap)

## Features

- links
- **inline** ~~text~~ *styles*
- multiline
  text
- `inline code`
-
    ```js
    console.log('code block');
    ```
- Katex - $x = {-b \pm \sqrt{b^2-4ac} \over 2a}$

要启用/禁用 MarkMap，请更新 ‘hugo.toml’/‘hugo.yaml’/‘hugo.json’：

• Configuration file:
• hugo.toml
• hugo.yaml
• hugo.json

[params.markmap]
enable = true

params:
  markmap:
    enable: true

{
  "params": {
    "markmap": {
      "enable": true
    }
  }
}

带有 Diagrams.net 的图表

[Diagrams.net]（https://diagrams.net/）（又名“draw.io”）提供了一个免费的开源图表编辑器，可以使用 Web 或桌面编辑器生成比 Mermaid 或 PlantUML 更广泛的图表。

默认情况下，使用该工具导出的 SVG 和 PNG 文件包含原始图表的源代码，这允许 diagrams.net 站点再次导入这些图像以供将来编辑。启用“draw.io”后，Docsy将检测到这一点，并自动在可以使用在线网站编辑的任何图像上添加“编辑”按钮。

将鼠标悬停在下面的图像上，然后单击编辑以立即开始使用它。 单击“保存”按钮将导致使用相同的文件名和文件类型导出编辑后的图表，并下载到您的浏览器。

由于图表数据是通过浏览器传输的，因此 diagrams.net 服务器根本不需要直接访问Docsy服务器上的内容。

要启用图表检测，请更新 ‘hugo.toml’/‘hugo.yaml’/‘hugo.json’：

• Configuration file:
• hugo.toml
• hugo.yaml
• hugo.json

[params.drawio]
enable = true

params:
  drawio:
    enable: true

{
  "params": {
    "drawio": {
      "enable": true
    }
  }
}

您还可以 [部署和使用您自己的服务器]（https://github.com/jgraph/docker-drawio/blob/master/README.md） 来编辑图表，在这种情况下，请更新配置以指向该服务器：

• Configuration file:
• hugo.toml
• hugo.yaml
• hugo.json

[params.drawio]
drawio_server = "https://app.mydrawioserver.example.com"

params:
  drawio:
    drawio_server: 'https://app.mydrawioserver.example.com'

{
  "params": {
    "drawio": {
      "drawio_server": "https://app.mydrawioserver.example.com"
    }
  }
}