Markdown 扩展语法：Hugo + FixIt

XOlDKING 发布于 2023/10/06

总计 4062 字｜更新于 2023/10/24｜- 次阅读｜- 条评论

系列 - Markdown 语法

本文列出了由 Hugo + FixIt 主题提供的 Markdown 扩展语法功能，为撰写博客文章提供更多便利。

转载（有增、改、合并）

原文作者：Lruihao
原文链接：Markdown 扩展语法
版权声明：CC BY-NC 4.0

信息

Hugo 是最受欢迎的开源静态网站生成器之一，号称是世界上最快的网站构建框架。
本博客目前使用 FixIt 主题，其示例网站中提供了详尽的中文文档。

Emoji 表情

启用

需在 Hugo 配置文件 hugo.toml 中将 enableEmoji 设置为 true。

FixIt 主题支持 Emoji Markdown 扩展语法的渲染，
其语法为：: ... :，其中 ... 为 emoji 表情代码，如：

1
2


去露营啦！:tent: 很快就回来。
真开心！:joy:

呈现的效果：

去露营啦！⛺ 很快就回来。
真开心！😂

参考

Emoji Cheat Sheet 列出了所有可用的 emoji 表情及其代码。

Font Awesome

启用

需在 Hugo 配置文件 hugo.toml 中将 params.page.fontawesome 设置为 true。

FixIt 主题使用 Font Awesome 作为图标库，
其语法为：:( ... ):，其中 ... 为 Font Awesome 图标代码，如：

1
2


去露营啦！:(fa-solid fa-campground fa-fw): 很快就回来。
真开心！:(fa-regular fa-grin-tears):

1
2


去露营啦！<i class="fa-solid fa-campground fa-fw"></i> 很快就回来。
真开心！<i class="fa-regular fa-grin-tears"></i>

呈现的效果：

去露营啦！很快就回来。
真开心！

参考

可在 Font Awesome 官网搜索所需的图标 class。

转义字符

在某些特殊情况下（如编写这个主题文档时），文章内容会与 Markdown 的基本或者扩展语法冲突，并且无法避免。借助转义字符语法可以帮助我们渲染出想要的内容，
其语法为：{?字符}。

1

{?X} -> X

例如，两个 : 会启用 emoji 语法。但有时候这不是我们想要的结果。可以像这样使用转义字符语法：

1

{?:}joy:

呈现的效果：

:joy: 而不是 😂

技巧

这个方法可以间接解决一个还未解决的 Hugo 的 issue。

另一个例子是：

1

[link{?]}(#escape-character)

呈现的效果：

[link](#escape-character) 而不是 link。

字符注音

启用

需在 Hugo 配置文件 hugo.toml 中将 params.page.ruby 设置为 true。

FixIt 主题支持 字符注音或者注释 Markdown 扩展语法的渲染，
其语法如下：

1

[Hugo]^(一个开源的静态网站生成工具）

使用 HTML 中的 <ruby> 标签进行渲染：

1
2
3
4
5
6


<strong>
    <ruby>
        Hugo
        <rt>一个开源的静态网站生成工具</rt>
    </ruby>
</strong>

呈现的效果：

Hugo一个开源的静态网站生成工具

分数

启用

需在 Hugo 配置文件 hugo.toml 中将 params.page.fraction 设置为 true。

FixIt 主题支持分数 Markdown 扩展语法的渲染，
其语法如下：

1
2


[浅色]/[深色]
[99]/[100]

使用 HTML 中的 <sub>、<sup> 标签进行渲染：

1
2


<sup>浅色</sup>/<sub>深色</sub>
<sup>90</sup>/<sub>100</sub>

呈现的效果：

^浅色/_深色
⁹⁰/₁₀₀

自定义属性

启用

需在 Hugo 配置文件 hugo.toml 中将 goldmark.parser.attribute.block 设置为 true。

Hugo 支持向 Markdown 块添加属性（如 CSS 类）。
其语法为：在一对花括号 {#my-id .my-class class="class1 class2"} 内添加 ID 及属性列表并将其放在需要装饰的 Markdown 元素之后

标题元素：在同一行其后添加；
块语法（如表格、列表、段落等）：在其后新一行添加。

带有 CSS 类的块引用：

1
2
3


> foo  
> bar
{#test-id .text-danger}

1
2
3
4


<blockquote id="test-id" class="text-danger">
    <p>foo</p>
    <p>bar</p>
</blockquote>

呈现的效果：

foo
bar

目前有一些限制：

表格：目前只能应用于完整表格，
列表：仅适用于 ul/ol 节点，例如：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


+ 水果
  + 苹果
  + 橙子
  + 香蕉
  {.text-success}
+ 乳制品
  + 牛奶
  + 奶酪
  {.text-warning}
{.text-primary}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


<ul class="text-primary">
    <li>水果
        <ul class="text-success">
            <li>苹果</li>
            <li>橙子</li>
            <li>香蕉</li>
        </ul>
    </li>
    <li>乳制品
        <ul class="text-warning">
            <li>牛奶</li>
            <li>奶酪</li>
        </ul>
    </li>
</ul>

呈现的效果：

水果
- 苹果
- 橙子
- 香蕉
乳制品
- 牛奶
- 奶酪

数学公式

启用

需在 Hugo 配置文件 hugo.toml 中将 params.page.math.enable 设置为 true。

FixIt 基于 $\KaTeX$ 支持数学公式 Markdown 语法的渲染。

注意

由于 Hugo 在渲染 Markdown 文档时会根据 _，*，>> 之类的语法生成 HTML 文档，并且有些转义字符形式的文本内容 (如 $，$，\[，\]，\\) 会自动进行转义处理，因此需要对这些地方进行额外的转义字符表达来实现自动渲染：

_ -> \_
* -> \*
>> -> \>>
\( -> \\(
\) -> \\)
\[ -> \\[
\] -> \\]
\\ -> \\\\

FixIt 主题支持 raw shortcode 以避免这些转义字符，方便我们编写原始数学公式内容。

一个 raw 示例：

1
2
3
4
5
6


{{< raw >}}行内公式：\(\mathbf{E}=\sum_{i} \mathbf{E}_{i}=\mathbf{E}_{1}+\mathbf{E}_{2}+\mathbf{E}_{3}+\cdots\){{< /raw >}}

{{< raw >}}
公式块：
\[ a=b+c \\ d+e=f \]
{{< /raw >}}

呈现的效果：

行内公式：$\mathbf{E}=\sum_{i} \mathbf{E}_{i}=\mathbf{E}_{1}+\mathbf{E}_{2}+\mathbf{E}_{3}+\cdots$

公式块： \[ a=b+c \\ d+e=f \]

参考

$\KaTeX$ 支持的 $\TeX$ 函数清单

行内公式

默认的行内公式分割符有：

$ ... $
$ ... $
- 转义的：\$ ... \$

例如：

1

$c = \pm\sqrt{a^2 + b^2}$ 和 \\(f(x)=\int_{-\infty}^{\infty} \hat{f}(\xi) e^{2 \pi i \xi x} d \xi\\)

呈现的效果：

$c = \pm\sqrt{a^2 + b^2}$ 和 $f(x)=\int_{-\infty}^{\infty} \hat{f}(\xi) e^{2 \pi i \xi x} d \xi$

技巧

可以在 Hugo 配置文件 hugo.toml 中通过

params.page.math.inlineLeftDelimiter 和 params.page.math.inlineLeftDelimiter 自定义行内公式的分割符。
params.page.math.blockLeftDelimiter 和 params.page.math.blockLeftDelimiter 自定义公式块的分割符。

公式块

默认的公式块分割符有：

$$ ... $$
\[ ... \]
- 转义的：\\[ ... \\]
\begin{equation} ... \end{equation}
- 不编号的：\begin{equation*} ... \end{equation*}
\begin{align} ... \end{align}
- 不编号的：\begin{align*} ... \end{align*}
\begin{alignat} ... \end{alignat}
- 不编号的：\begin{alignat*} ... \end{alignat*}
\begin{gather} ... \end{gather}
- 不编号的：\begin{gather*} ... \end{gather*}
\begin{CD} ... \end{CD}

警告

当公式块中存在换行时，请谨慎开启 goldmark.renderer.hardWraps，设置为 true 时Goldmark 会将换行符呈现为 <br> 元素。

例如：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32


$$ c = \pm\sqrt{a^2 + b^2} $$

\\[ f(x)=\int_{-\infty}^{\infty} \hat{f}(\xi) e^{2 \pi i \xi x} d \xi \\]

\begin{equation*}
  \rho \frac{\mathrm{D} \mathbf{v}}{\mathrm{D} t}=\nabla \cdot \mathbb{P}+\rho \mathbf{f}
\end{equation*}

\begin{equation}
  \mathbf{E}=\sum_{i} \mathbf{E}\_{i}=\mathbf{E}\_{1}+\mathbf{E}\_{2}+\mathbf{E}_{3}+\cdots
\end{equation}

\begin{align}
  a&=b+c \\\\
  d+e&=f
\end{align}

\begin{alignat}{2}
   10&x+&3&y = 2 \\\\
   3&x+&13&y = 4
\end{alignat}

\begin{gather}
   a=b \\\\
   e=b+c
\end{gather}

\begin{CD}
   A @>a\>> B \\\\
@VbVV @AAcA \\\\
   C @= D
\end{CD}

呈现的效果：

$$ c = \pm\sqrt{a^2 + b^2} $$

\[ f(x)=\int_{-\infty}^{\infty} \hat{f}(\xi) e^{2 \pi i \xi x} d \xi \]

\begin{equation*} \rho \frac{\mathrm{D} \mathbf{v}}{\mathrm{D} t}=\nabla \cdot \mathbb{P}+\rho \mathbf{f} \end{equation*}

\begin{equation} \mathbf{E}=\sum_{i} \mathbf{E}_{i}=\mathbf{E}_{1}+\mathbf{E}_{2}+\mathbf{E}_{3}+\cdots \end{equation}

\begin{align} a&=b+c \\ d+e&=f \end{align}

\begin{alignat}{2} 10&x+&3&y = 2 \\ 3&x+&13&y = 4 \end{alignat}

\begin{gather} a=b \\ e=b+c \end{gather}

\begin{CD} A @>a>> B \\ @VbVV @AAcA \\ C @= D \end{CD}

化学方程式

启用

需在 Hugo 配置文件 hugo.toml 中将 params.page.math.mhchem 设置为 true。

mhchem 是一个 $\KaTeX$ 的插件。

FixIt 基于 mhchem 插件支持在文章中轻松编写漂亮的化学方程式。

1
2
3


$$ \ce{CO2 + C -> 2 CO} $$

$$ \ce{Hg^2+ ->[I-] HgI2 ->[I-] [Hg^{II}I4]^2-} $$

呈现的效果：

$$ \ce{CO2 + C -> 2 CO} $$

$$ \ce{Hg^2+ ->[I-] HgI2 ->[I-] [Hg^{II}I4]^2-} $$

公式源码复制

启用

需在 Hugo 配置文件 hugo.toml 中将 params.page.math.copyTex 设置为 true。

Copy-tex 是一个 $\KaTeX$ 的插件。

FixIt 基于 Copy-tex 插件支持在选择并复制 $\KaTeX$ 渲染的公式时，将其 $\LaTeX$ 源代码复制到剪贴板。

选择并复制上述渲染的公式，可以发现复制的内容为 $\LaTeX$ 源代码。

代码块扩展语法

代码块属性

可以在代码块语言设置后，将属性添加进花括号 { } 中，以 , 分隔。可接受的属性有：

title：代码块的标题
linenos：行号设置，可接受的选项有
- true：显示行号
- false：隐藏行号
- inline：复制代码时同时复制行号
- table：复制代码时不复制行号
hl_lines：高亮显示的行号 5 或行号范围 "10-15"
linenostart：起始行号

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


```go {title="test.go", linenos="table", hl_lines=[8, "15-17"], linenostart=199}
// GetTitleFunc returns a func that can be used to transform a string to
// title case.
//
// The supported styles are
//
// - "Go" (strings.Title)
// - "AP" (see https://www.apstylebook.com/)
// - "Chicago" (see https://www.chicagomanualofstyle.org/home.html)
//
// If an unknown or empty style is provided, AP style is what you get.
func GetTitleFunc(style string) func(s string) string {
  switch strings.ToLower(style) {
  case "go":
    return strings.Title
  case "chicago":
    return transform.NewTitleConverter(transform.ChicagoStyle)
  default:
    return transform.NewTitleConverter(transform.APStyle)
  }
}
```

呈现的效果：

199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218


// GetTitleFunc returns a func that can be used to transform a string to
// title case.
//
// The supported styles are
//
// - "Go" (strings.Title)
// - "AP" (see https://www.apstylebook.com/)
// - "Chicago" (see https://www.chicagomanualofstyle.org/home.html)
//
// If an unknown or empty style is provided, AP style is what you get.
func GetTitleFunc(style string) func(s string) string {
  switch strings.ToLower(style) {
  case "go":
    return strings.Title
  case "chicago":
    return transform.NewTitleConverter(transform.ChicagoStyle)
  default:
    return transform.NewTitleConverter(transform.APStyle)
  }
}

GoAT 图示

GoATGo ASCII Tool 是 markdeep.mini.js 图像生成器的 Go 语言实现。

要使用 GoAT，只需在代码块中输入 GoAT 代码，并将语言设置为 goat，例如：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26


```goat
+-------------------+                           ^                      .---.
|    A Box          |__.--.__    __.-->         |      .-.             |   |
|                   |        '--'               v     | * |<---        |   |
+-------------------+                                  '-'             |   |
                       Round                                       *---(-. |
  .-----------------.  .-------.    .----------.         .-------.     | | |
 |   Mixed Rounded  | |         |  / Diagonals  \        |   |   |     | | |
 | & Square Corners |  '--. .--'  /              \       |---+---|     '-)-'       .--------.
 '--+------------+-'  .--. |     '-------+--------'      |   |   |       |        / Search /
    |            |   |    | '---.        |               '-------'       |       '-+------'
    |<---------->|   |    |      |       v                Interior                 |     ^
    '           <---'      '----'   .-----------.              ---.     .---       v     |
 .------------------.  Diag line    | .-------. +---.              \   /           .     |
 |   if (a > b)     +---.      .--->| |       | |    | Curved line  \ /           / \    |
 |   obj->fcn()     |    \    /     | '-------' |<--'                +           /   \   |
 '------------------'     '--'      '--+--------'      .--. .--.     |  .-.     +Done?+-'
    .---+-----.                        |   ^           |\ | | /|  .--+ |   |     \   /
    |   |     | Join        \|/        |   | Curved    | \| |/ | |    \    |      \ /
    |   |     +---->  o    --o--        '-'  Vertical  '--' '--'  '--  '--'        +  .---.
 <--+---+-----'       |     /|\                                                    |  | 3 |
                      v                             not:line    'quotes'        .-'   '---'
  .-.             .---+--------.            /            A || B   *bold*       |        ^
 |   |           |   Not a dot  |      <---+---<--    A dash--is not a line    v        |
  '-'             '---------+--'          /           Nor/is this.            ---
```

参考

详细介绍及更多示例请参考 GitHub/blampe/goat。

Mermaid 图表

Mermaid 是一个基于 JavaScript 的图表绘制工具，通过解析类 Markdown 的文本语法来实现图标的创建和动态修改。

要使用 Mermaid，只需在代码块中输入 Mermaid 代码，并将语言设置为 mermaid。

参考

详细介绍及更多示例请参考 Mermaid 官方文档或 GitHub/mermaid-js/mermaid。

主题

以下为 Mermaid 的可用主题：

default - 这是所有图表的默认主题。
neutral - 这个主题非常适合黑白打印的文档。
dark - 这个主题适合与深色元素或暗模式搭配使用。
forest - 这个主题包含各种绿色。
base - 这是唯一可以修改的主题。使用此主题作为自定义的基础。

为 Mermaid 图表设定主题：

全站图表：在 Hugo 配置文件 hugo.toml 中将 params.mermiad.themes 设置为上述可用主题。
单个图表：在 Markdown 代码首行插入 %%{init: {'theme':'可用主题'}}%%。

参考

请前往 Theme Configuration | Mermaid 页面，了解有关动态和集成主题配置的更多信息。

流程图

1
2
3
4
5
6
7


```mermaid
flowchart LR
A[Hard] -->|Text| B(Round)
B --> C{Decision}
C -->|One| D[Result 1]
C -->|Two| E[Result 2]
```

时序图

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


```mermaid
sequenceDiagram
Alice->>John: Hello John, how are you?
loop Healthcheck
    John->>John: Fight against hypochondria
end
Note right of John: Rational thoughts!
John-->>Alice: Great!
John->>Bob: How about you?
Bob-->>John: Jolly good!
```

类图

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


```mermaid
classDiagram
Class01 <|-- AveryLongClass : Cool
Class03 *-- Class04
Class05 o-- Class06
Class07 .. Class08
Class09 --> C2 : Where am i?
Class09 --* C3
Class09 --|> Class07
Class07 : equals()
Class07 : Object[] elementData
Class01 : size()
Class01 : int chimp
Class01 : int gorilla
Class08 <--> C2: Cool label
```

状态图

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


```mermaid
stateDiagram
    direction LR
    [*] --> Still
    Still --> [*]
    Still --> Moving
    Moving --> Still
    Moving --> Crash
    Crash --> [*]
```

甘特图

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


```mermaid
gantt
dateFormat  YYYY-MM-DD
title Adding GANTT diagram to mermaid
excludes weekdays 2014-01-10

section A section
Completed task  :done,    des1, 2014-01-06,2014-01-08
Active task     :active,  des2, 2014-01-09, 3d
Future task     :         des3, after des2, 5d
Future task2    :         des4, after des3, 5d
```

饼图

1
2
3
4
5
6


```mermaid
pie
    "Dogs" : 386
    "Cats" : 85
    "Rats" : 15
```

Git 图

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44


```mermaid
gitGraph
    commit
    branch hotfix
    checkout hotfix
    commit
    branch develop
    checkout develop
    commit id:"ash" tag:"abc"
    branch featureB
    checkout featureB
    commit type:HIGHLIGHT
    checkout main
    checkout hotfix
    commit type:NORMAL
    checkout develop
    commit type:REVERSE
    checkout featureB
    commit
    checkout main
    merge hotfix
    checkout featureB
    commit
    checkout develop
    branch featureA
    commit
    checkout develop
    merge hotfix
    checkout featureA
    commit
    checkout featureB
    commit
    checkout develop
    merge featureA
    branch release
    checkout release
    commit
    checkout main
    commit
    checkout release
    merge main
    checkout develop
    merge release
```