sheetung
sheetung

Markdown 扩展语法

西塘 收录于 技术笔记 和 Markdown 语法
 约 1300 字 预计阅读 6 分钟 - 次阅读  

本文展示了 FixIt 风格的 MarkdownFixIt Flavored Markdown 扩展语法。

警示

警示（Alert）也被称为 Callout 或 Admonition，是用于强调关键信息的引用块。

基本语法

使用基本的 Markdown 语法，每个警示的第一行是一个警示指示符，由一个感叹号和警示类型组成，用中括号括起来。

Alert 基本语法与 GitHub、Obsidian 和 Typora 兼容。

以下是所有五种类型的示例：

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

> [!NOTE]
> 突出显示用户应考虑的信息，即使只是浏览也应考虑。

> [!TIP]
> 可选信息，可帮助用户取得更大的成功。

> [!IMPORTANT]
> 用户成功所需的关键信息。

> [!WARNING]
> 由于存在潜在风险，需要用户立即关注的关键内容。

> [!CAUTION]
> 操作的潜在负面后果。

呈现的输出效果如下：

注意

突出显示用户应考虑的信息，即使只是浏览也应考虑。

提示

可选信息，可帮助用户取得更大的成功。

重要

用户成功所需的关键信息。

警告

由于存在潜在风险，需要用户立即关注的关键内容。

小心

操作的潜在负面后果。

扩展语法

使用扩展 Markdown 语法，你可以选择包含警示符号或警示标题。警示符号是 + 或 - 之一。通常用于指示警示是否可以图形折叠。

Alert 扩展语法与 Obsidian 和 Fixit admonition shortcode 兼容。

警告

扩展语法与 GitHub 或 Typora 不兼容。如果包含警示符号或警示标题，这些应用程序会将 Markdown 渲染为引用块。

更改标题

默认警示标题是其类型标识符的标题大小写。你可以通过在类型标识符后添加文本来更改它：

1
2

> [!NOTE] FixIt
> 一个简洁、优雅且高效的 Hugo 主题。
FixIt

一个简洁、优雅且高效的 Hugo 主题。

你甚至可以省略正文来创建仅标题的警示：

1

> [!TIP] 仅标题的警示
仅标题的警示

可折叠警示

你可以通过在类型标识符后直接添加加号（+）或减号（-）来使警示可折叠。

1
2
3
4
5

> [!WARNING]+ 辐射危害
> 请勿在没有防护装备的情况下接近或操作。

> [!QUESTION]- 警示可以折叠吗？
> 是的！在可折叠警示中，内容在折叠时被隐藏。
辐射危害

请勿在没有防护装备的情况下接近或操作。

警示可以折叠吗？

是的！在可折叠警示中，内容在折叠时被隐藏。

嵌套警示

你可以在多个级别中嵌套警示。

1
2
3

> [!question] 警示可以嵌套吗？
> > [!todo] 可以！它们可以。
> > > [!example] 你甚至可以使用多层嵌套。
警示可以嵌套吗？
可以！它们可以。
你甚至可以使用多层嵌套。

仅内容警示

你可以通过在类型标识符后直接添加波浪号（~）来创建仅内容警示。

这是 FixIt 独有的扩展语法，与 Obsidian 或其他 Markdown 应用不兼容。
1
2

> [!TIP]~
> 这是一个没有标题的仅内容警示。

这是一个没有标题的仅内容警示。

支持的类型

Alert 扩展语法支持 13 种类型的警示横幅，除非你自定义 Admonition，否则任何不支持的类型都会默认为 note 类型。类型标识不区分大小写。

类型 别名
note —
abstract summary, tldr
info —
todo —
tip hint, important
success check, done
question help, faq
warning caution, attention
failure fail, missing
danger error
bug —
example —
quote cite

颜色预览

在文章内容中，可以使用反引号在句子中标注颜色。反引号内支持的颜色模型将显示颜色的可视化效果。

1

对于 `Light` 模式，背景色为`#ffffff`，对于 `Dark` 模式，背景颜色为`#000000`。

对于 Light 模式，背景色为#ffffff，对于 Dark 模式，背景颜色为#000000。

下面是当前支持的颜色模型。

Color 语法 示例 输出
HEX `#RRGGBB` `#0969DA` #0969DA
RGB `rgb(R,G,B)` `rgb(9, 105, 218)` rgb(9, 105, 218)
HSL `hsl(H,S,L)` `hsl(212, 92%, 45%)` hsl(212, 92%, 45%)

注意

  • 支持的颜色模型在反引号内不能有任何前导或尾随空格。
  • 颜色的可视化效果兼容 GitHub 支持的颜色模型。

任务列表

要创建任务列表，请在每个列表项前添加一个短横线和空格，然后跟上 [ ]。

1
2

- [x] 这是一个已完成的任务。
- [ ] 这是一个未完成的任务。

呈现的输出效果如下：

  • 这是一个已完成的任务。
  • 这是一个未完成的任务。

你可以在括号内使用任何字符来标记任务为已完成或其他状态。

1
2
3
4
5
6
7
8

- [ ] 未完成
- [x] 已完成
- [/] 进行中
- [-] 已取消
- [<] 已计划
- [>] 已重新计划
- [!] 重要
- [?] 问题

呈现的输出效果如下：

  • 未完成
  • 已完成
  • 进行中
  • 已取消
  • 已计划
  • 已重新计划
  • 重要
  • 问题

提示

如果你想要更多类型的任务列表，请查看进阶篇 - 自定义任务列表章节。

下划线

如何开启 Hugo 扩展语法

下划线、标记文本、下标和上标语法默认关闭，需更新 Hugo 版本到 0.128.0 以上且开启以下的配置：

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

[markup]
[markup.goldmark]
[markup.goldmark.extensions]
strikethrough = false

[markup.goldmark.extensions.extras]
[markup.goldmark.extensions.extras.delete]
enable = true
[markup.goldmark.extensions.extras.insert]
enable = true
[markup.goldmark.extensions.extras.mark]
enable = true
[markup.goldmark.extensions.extras.subscript]
enable = true
[markup.goldmark.extensions.extras.superscript]
enable = true

Hugo 支持一种 下划线 Markdown 扩展语法：

1

FixIt 主题的作者是 ++Lruihao++。

呈现的输出效果如下：

FixIt 主题的作者是 Lruihao。

标记文本

Hugo 支持一种 标记文本 Markdown 扩展语法：

1

==FixIt== 是一个很棒的 Hugo 主题！

呈现的输出效果如下：

FixIt 是一个很棒的 Hugo 主题！

扩展的标记文本语法支持 6 种类型的标记文本。

1
2
3
4
5
6

==Primary==[primary]
==Secondary==[secondary]
==Success==[success]
==Info==[info]
==Warning==[warning]
==Danger==[danger]

呈现的输出效果如下：

Primary Secondary Success Info Warning Danger

除非你自定义标记文本，否则任何不支持的类型都会默认为 default 类型。

1

==这是一个带有粉色的自定义类型。==[pink]

在你的项目目录 assets/css/_custom.scss 中添加以下 CSS 来自定义：

1
2
3

.mark-pink {
  --fi-mark-background-color: pink;
}

呈现的输出效果如下：

这是一个带有粉色的自定义类型。

输出的 HTML 看起来像这样：

1

<mark class="mark-pink">这是一个带有粉色的自定义类型。</mark>

下标

Hugo 支持一种 下标 Markdown 扩展语法：

1

水的化学式是 H~2~O。

呈现的输出效果如下：

水的化学式是 H2O。

上标

Hugo 支持一种 上标 Markdown 扩展语法：

1

2^10^ 等于 1024。

呈现的输出效果如下：

210 等于 1024。

Emoji 支持

这部分内容在 Emoji 支持页面中介绍。

数学公式

FixIt 基于 KaTeX 或 MathJax 提供数学公式的支持，默认引擎为 KaTeX。

你可以在主题配置中修改数学公式自动渲染的相关配置：

 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

[markup]
[markup.goldmark]
[markup.goldmark.extensions]
[markup.goldmark.extensions.passthrough]
enable = true

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

[params]
[params.page]
[params.page.math]
enable = true
type = "katex"

[params.page.math.katex]
copyTex = true
throwOnError = false
errorColor = "#ff4949"

KaTeX

KaTeX 通过 Hugo 的 transform.ToMath 函数在 服务器端渲染，所以客户端加载速度更快。

提示

有一份 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=±a2+b2c = \pm\sqrt{a^2 + b^2} 和 f(x)=∫−∞∞f^(ξ)e2πiξxdξf(x)=\int_{-\infty}^{\infty} \hat{f}(\xi) e^{2 \pi i \xi x} d \xi

公式块

默认的公式块分割符有：

  • $$ ... $$

例如：

 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

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

$$
\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=±a2+b2 c = \pm\sqrt{a^2 + b^2} ρDvDt=∇⋅P+ρf \begin{equation*} \rho \frac{\mathrm{D} \mathbf{v}}{\mathrm{D} t}=\nabla \cdot \mathbb{P}+\rho \mathbf{f} \end{equation*} E=∑iE_i=E_1+E_2+E3+⋯ \begin{equation} \mathbf{E}=\sum_{i} \mathbf{E}\_{i}=\mathbf{E}\_{1}+\mathbf{E}\_{2}+\mathbf{E}_{3}+\cdots \end{equation} a=b+cd+e=f \begin{align} a&=b+c \\ d+e&=f \end{align} 10x+3y=23x+13y=4 \begin{alignat}{2} 10&x+&3&y = 2 \\ 3&x+&13&y = 4 \end{alignat} a=be=b+c \begin{gather} a=b \\ e=b+c \end{gather} A→aBb↓↑cC=D \begin{CD} A @>a>> B \\ @VbVV @AAcA \\ C @= D \end{CD}

复制公式

Copy-tex 是一个 KaTeX 的插件。通过这个扩展，在选择并复制 KaTeX 渲染的公式时，会将其 LaTeX 源代码复制到剪贴板。

在主题配置中的 [params.page.math.katex] 下面设置属性 copyTex = true 来启用 Copy-tex。

化学方程式

mhchem 是一个 KaTeX 的插件，提供了 \ce 和 \pu 函数。通过这个扩展，你可以在文章中轻松编写漂亮的化学方程式。

1
2
3
4
5

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

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

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

呈现的输出效果如下：

COX2+C→2 CO \ce{CO2 + C -> 2 CO} HgX2+→IX−HgIX2→IX−[HgXIIIX4]X2− \ce{Hg^2+ ->[I-] HgI2 ->[I-] [Hg^{II}I4]^2-} Cp[HX2O(l)]=75.3 Jmol KC_p[\ce{H2O(l)}] = \pu{75.3 J // mol K}

自定义宏

你可以在主题配置中的 [params.page.math.katex.macros] 下面添加自定义宏。

例如：

1
2

[params.page.math.katex.macros]
"\\f" = "#1f(#2)" # usage: $\f{a}{b}$

然后在文章中使用：

1
2
3
4
5

$$
\f\relax{x} = \int_{-\infty}^\infty
    \f\hat\xi\,e^{2 \pi i \xi x}
    \,d\xi
$$

呈现的输出效果如下：

\fx=∫−∞∞\fξ^ e2πiξx dξ \f\relax{x} = \int_{-\infty}^\infty \f\hat\xi\,e^{2 \pi i \xi x} \,d\xi

错误信息

如果在渲染公式时遇到错误，KaTeX 会在页面上显示错误信息。

例如：

1

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

呈现的输出效果如下，鼠标悬停在错误信息上可以查看详细的错误信息：

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

小心

如果你设置 params.page.math.katex.throwOnError 为 true，则会抛出错误并停止渲染。

MathJax

MathJax 在页面加载后通过 JavaScript 进行 客户端渲染，速度较慢但功能更加强大。

这部分内容在 MathJax 支持页面中介绍。

字符注音或者注释

FixIt 主题支持一种 字符注音或者注释 Markdown 扩展语法：

1

[FixIt]^(一个简洁、优雅且高效的 Hugo 主题)

呈现的输出效果如下：

FixIt一个简洁、优雅且高效的 Hugo 主题

分数

FixIt 主题支持一种 分数 Markdown 扩展语法：

1
2
3

[浅色]/[深色]

[99]/[100]

呈现的输出效果如下：

浅色/深色

90/100

Font Awesome

FixIt 主题使用 Font Awesome V6 作为图标库。你同样可以在文章中轻松使用这些图标。

从 Font Awesome 网站上获取所需的图标 class。

1
2
3

去露营啦！:(fa-solid fa-campground fa-fw): 很快就回来。

真开心！:(fa-regular fa-grin-tears):

呈现的输出效果如下：

去露营啦！ 很快就回来。

真开心！

转义字符

在某些特殊情况下，你的文章内容会与 Markdown 的基本或者扩展语法冲突，并且无法避免。转义字符语法可以帮助你渲染出想要的内容：

1

{?X} -> X

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

1

{?:}joy:

呈现的输出效果如下：

:joy: 而不是 😂

提示

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

另一个例子是：

1

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

呈现的输出效果如下：

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

Markdown 属性

更新你的站点配置以启用块级元素的 Markdown 属性。

Hugo 支持图像和块元素上的 Markdown 属性，包括块引用、围栏代码块、标题、水平线、列表、段落和表格。

语法 

1
2

some Markdown content
{#id .class1 .class2 key1="value1" key2="value2"}

在大多数情况下，将属性列表放置在标记元素下方。对于标题和围栏代码块，将属性列表放在右侧。

标记元素 属性放置的位置
blockquote 底部
fenced code block 右侧
heading 右侧
horizontal rule 底部
image 底部
list 底部
paragraph 底部
table 底部

例子

分割线

带有 CSS 类的分割线：

1
2

---
{.awesome-hr}

呈现的输出如下所示：

引用

带有 CSS 类的块引用：

1
2

> The quick brown fox jumps over the lazy dog.
{.blockquote-center}

呈现的输出如下所示：

The quick brown fox jumps over the lazy dog.

表格 & 列表

目前有一些限制：对于表格，你目前只能将其应用于完整表格，而对于列表，仅适用于 ul/ol 节点，例如：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

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

呈现的输出如下所示：

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

代码块扩展语法

FixIt 主题扩展了标准 Markdown 代码围栏，支持高级功能，包括图表、图形和交互式可视化。这些扩展的代码围栏使你能够直接在 Markdown 文件中创建丰富的动态内容。

语法

扩展的代码围栏使用与标准 Markdown 相同的三重反引号语法，但使用特定语言标识符来触发特殊的渲染引擎：

1
2
3

```LANG [OPTIONS]
// 在这里输入特定语言的内容
```

语言

这些功能在 FixIt 主题中自动启用，无需额外配置，只需在代码围栏中使用相应的语言标识符，内容就会使用相应的引擎进行渲染。

语言标识符 描述
goat ASCII 艺术图表，渲染为可缩放的矢量图形
mermaid 专业图表，包括流程图、时序图等
echarts 交互式数据可视化图表和图形
timeline 具有丰富格式的时间线事件显示
json 格式化和可折叠的 JSON 数据视图
file-tree 渲染文件和目录结构为交互式树
toggle 以 TOML、YAML 和 JSON 格式渲染语法高亮的配置数据

选项

你可以通过 Hugo 语法高亮选项、主题代码块配置、Markdown 属性或者以下选项来自定义你的代码块：

选项 描述 类型
title 代码块标题 string
name 代码块名称或标签项名称 string
group 代码块标签组名称 string
before_tabs 在标签项之前显示的内容 string
filename 代码块文件名 string

group 和 name 选项可以一起使用来创建标签页式的代码块。例如：

1
2
3
4
5
6
7

```python {group="languages", name="Hi Python"}
print('Hello, world!')
```

```js {group="languages", name="Hi JS", .active}
console.log('Hello, world!');
```

呈现的输出如下所示：

1

print('Hello, world!')
1

console.log('Hello, world!');

相关内容

收录于 合集・Markdown 语法 2
更新于 2026-05-17 
CC BY-NC-SA 4.0
MarkdownHugo
返回 | 主页
西塘 支付宝支付宝
西塘 微信微信

目录