写作语法速查（写法 + 效果对照）

本文档列出本站支持的全部写作语法，每条都给出「写法」与「实际效果」对照，方便直接照着抄。

提示：右侧目录可快速跳转。

一、快速开始

新建文章（自动套用模板）：

1
hugo new content posts/我的新文章.md

本地预览（写完保存自动刷新）：

1
hugo server -D

推送发布（等价于原来 Hexo 的 hexo push）：

1
2
./push.sh        # Git Bash
push.bat         # 或直接双击这个文件

二、Front Matter（文章头部配置）

写法：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
---
title: "文章标题"
date: 2026-10-07T10:00:00+08:00
lastmod: 2026-10-07T10:00:00+08:00
draft: false
description: "文章摘要，显示在列表页与搜索结果里"
tags: ["标签一", "标签二"]
categories: ["随笔"]
keywords: ["关键词"]
math: true                 # 开启数学公式
ShowToc: true              # 显示目录
cover:
  image: "/images/cover/x.jpg"
  alt: "封面描述"
  caption: "封面说明"
---

说明：所有字段都可选，不写就用 hugo.yaml 里的全局默认值。draft: true 的文章不会发布。

三、文本与结构

3.1 标题

写法：

1
2
3
## 二级标题
### 三级标题
#### 四级标题

效果：见本页各级标题（目录只收录二至四级）。

3.2 文本样式

写法：

1
**加粗**、*斜体*、***粗斜体***、~~删除线~~、`行内代码`

效果：

加粗、斜体、粗斜体、~~删除线~~、行内代码

3.3 列表

写法：

1
2
3
4
5
6
- 无序项
- 无序项
  - 嵌套项（缩进 2 空格）

1. 有序项
2. 有序项

效果：

无序项
无序项
- 嵌套项

有序项
有序项

3.4 任务列表

写法：

1
2
- [x] 已完成的任务
- [ ] 未完成的任务

效果：

已完成的任务
未完成的任务

3.5 引用

写法：

1
2
3
> 引用文字，支持 **Markdown**。
>
> 第二段。

效果：

引用文字，支持 Markdown。
第二段。

3.6 表格

写法：

1
2
3
| 左对齐 | 居中 | 右对齐 |
|:---|:---:|---:|
| 内容 | 内容 | 内容 |

效果：

左对齐	居中	右对齐
内容	内容	内容

3.7 分割线

写法（前后各留一个空行）：

1
---

效果：

3.8 脚注

写法：

1
2
3
这句话有脚注[^1]。

[^1]: 脚注内容写在这里。

效果：

这句话有脚注¹。

3.9 链接

写法：

1
2
[外部链接](https://gohugo.io)
[站内链接]({{< ref "posts/syntax-demo.md" >}})

效果：外部链接｜站内链接

站内跳转推荐用 ref，文章改名后链接自动更新。

3.10 图片

写法：

1
![图片说明](/images/example.png)

效果：PaperMod 会自动把 alt 显示为图片下方的图注。更精细的控制用 figure 短代码（见 5.1）。

四、代码

4.1 行内代码

写法：`const a = 1` → 效果：const a = 1

4.2 代码块

写法：

1
2
3
4
```python
def hello(name):
    return f"Hello, {name}"
```

效果：

1
2
def hello(name):
    return f"Hello, {name}"

代码块自动语法高亮，右上角带复制按钮。

4.3 高亮指定行

写法：

1
2
3
4
{{< highlight python "linenos=table,hl_lines=2" >}}
def hello():
    print("这行会高亮")
{{< /highlight >}}

效果：

1
2
def hello():
    print("这行会高亮")

五、短代码（Shortcodes）

5.1 figure 图片（带标题与图注）

写法：

1
{{< figure src="/images/example.png" title="图片标题" caption="图片说明，支持 **Markdown**" align="center" >}}

参数：src（必需）、title、caption、alt、width、height、align="center"、link、target、rel、class

5.2 collapse 折叠

写法：

1
2
3
{{< collapse summary="点击展开" >}}
折叠里的内容，支持 **Markdown**。
{{< /collapse >}}

效果：

点击展开

折叠里的内容，支持 Markdown。

列表也行
代码块也行

⚠️ 必须写 summary="标题"，写成位置参数 {{< collapse "标题" >}} 会没有标题。

5.3 note 提示框（本站增强）

写法：

1
2
3
{{< note info >}}
这是**信息**提示框，内部支持 Markdown。
{{< /note >}}

五种类型：

info —— 一般信息提示

success —— 成功 / 推荐做法

warning —— 注意事项

danger —— 危险 / 强烈警告

primary —— 重点强调

带标题（第二个参数）：

1
2
3
{{< note warning "前置条件" >}}
内容…
{{< /note >}}

效果：

需要先安装 Hugo extended 版本。

为什么用短代码而不是 HTML？ 直接写 <div class="note info">…</div> 时，块级 HTML 内部的 Markdown 不会被解析（CommonMark 规范行为）， **加粗** 会原样显示成星号。短代码会先把内容渲染成 Markdown 再填入。

5.4 rawhtml 原始 HTML

写法：

1
2
3
{{< rawhtml >}}
<div class="my-widget">任意 HTML</div>
{{< /rawhtml >}}

5.5 音频与视频

写法：

1
2
3
{{< audio src="/media/demo.mp3" >}}
{{< video src="/media/demo.mp4" >}}
{{< youtube i8Iiv9yFTdM >}}

5.6 行内小图标

写法：

1
{{< inTextImg url="/images/logo.svg" alt="logo" height="20" >}}

5.7 details 折叠（Hugo 原生）

写法：

1
2
3
{{< details "点击展开" >}}
内容，支持 **Markdown**。
{{< /details >}}

效果：

Details

内容，支持 Markdown。

5.8 显示短代码语法本身

想在文章里展示短代码而不让它执行，用 /* */ 包裹：

写法：

1
{{< note info >}}内容{{< /note >}}

页面效果：会原样显示成

内容

（纯文本），而不是渲染成提示框。

若只写单边（如 {{< note info >}} 而没有对应的闭合标记），Hugo 会报 shortcode "note" must be closed or self-closed 构建失败 —— 成对书写即可。

六、增强语法

6.1 行内高亮

写法：

1
2
3
4
5
<mark class="hl red">红色重点</mark>
<mark class="hl green">绿色</mark>
<mark class="hl blue">蓝色</mark>
<mark class="hl yellow">黄色</mark>
<mark class="hl purple">紫色</mark>

效果：

红色重点、绿色、蓝色、黄色、紫色

6.2 两栏对比

写法：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
<div class="columns">
<div>
<h4>方案 A</h4>
<p>内容（这里用 HTML 标签，不用 Markdown）</p>
</div>
<div>
<h4>方案 B</h4>
<p>内容</p>
</div>
</div>

效果：

方案 A

简单直观，实现快，适合小数据量场景。

方案 B

前期投入大，但数据量增长后优势明显。

注意：columns 内部用 HTML 标签（<p> <h4>），不要写 Markdown —— 原因同上（块级 HTML 内不解析 Markdown）。

6.3 数学公式

行内公式 —— 写法： $E = mc^2$ → 效果： $E = mc^2$

单行独立公式 —— 写法：

1
$$\int_{-\infty}^{+\infty} e^{-x^2} \, dx = \sqrt{\pi}$$

效果：

\int_{-\infty}^{+\infty} e^{-x^2} \, dx = \sqrt{\pi}

多行 / 复杂公式 —— 必须用 math 短代码包裹：

1
2
3
4
5
6
{{< math >}}
\begin{pmatrix}
a & b \\
c & d
\end{pmatrix}
{{< /math >}}

效果：

\begin{pmatrix} a & b \\ c & d \end{pmatrix} \begin{pmatrix} x \\ y \end{pmatrix} = \begin{pmatrix} ax + by \\ cx + dy \end{pmatrix}

⚠️ 多行公式直接写多行 $$ 会被 Markdown 解析器破坏（\end{pmatrix} 会被当成标题），必须用 math 短代码。

6.4 Mermaid 图表

直接写代码块即可（不需要记短代码）。

流程图 —— 写法：

1
2
3
4
5
```mermaid
flowchart TD
    A[开始] --> B{判断}
    B -->|是| C[结束]
```

效果：

flowchart TD
    A[开始] --> B{判断}
    B -->|是| C[结束]

时序图 —— 写法：

1
2
3
4
5
```mermaid
sequenceDiagram
    用户->>服务器: 发起请求
    服务器-->>用户: 返回数据
```

效果：

sequenceDiagram
    用户->>服务器: 发起请求
    服务器-->>用户: 返回数据

饼图 —— 写法：

1
2
3
4
5
6
```mermaid
pie title 时间分配
    "写作" : 45
    "阅读" : 30
    "其他" : 25
```

效果：

pie title 时间分配
    "写作" : 45
    "阅读" : 30
    "其他" : 25

图表配色会自动跟随明暗主题切换。

七、常用组合

一段技术说明可以这样写：

写法：

1
2
3
4
5
6
7
{{< note warning "前置条件" >}}
需要 **Hugo extended** 版本。
{{< /note >}}

```mermaid
flowchart LR
    A[输入] --> B[处理] --> C[输出]

核心公式：

T(n) = 2T(n/2) + O(n)

1
2
3
4
5
6
7
8

**效果**：


需要 Hugo extended 版本。

```mermaid
flowchart LR
    A[输入] --> B[处理] --> C[输出]

核心公式：

T(n) = 2T(n/2) + O(n)

八、常见坑

现象	原因	解决
提示框里 `加粗` 没生效	用了 HTML 写法，块级 HTML 内不解析 Markdown	改用 `note` 短代码
多行公式显示成标题	直接写了多行 `$$…$$`	用 `math` 短代码包裹
Mermaid 显示为代码块	语言名写错	必须是 ```mermaid（全小写）
`collapse` 没有标题	用了位置参数	改成 `summary="标题"`
文章写了但不显示	`date` 是未来时间	改成过去时间或加 `--buildFuture`
文章写了但不显示	`draft: true`	改成 `false`，或预览加 `-D`
短代码被当成文字显示	参数格式错误	检查尖括号与引号

九、更多

Hugo + PaperMod 写作语法大全 —— 含 Front Matter 全字段、各短代码参数细节
从 Hexo(AnZhiYu) 迁移到 Hugo(PaperMod) 完整记录
Hugo 博客多平台部署与 baseURL 配置

脚注内容写在这里。 ↩︎

一、快速开始#

二、Front Matter（文章头部配置）#

三、文本与结构#

3.1 标题#

3.2 文本样式#

3.3 列表#

3.4 任务列表#

3.5 引用#

3.6 表格#

3.7 分割线#

3.8 脚注#

3.9 链接#

3.10 图片#

四、代码#

4.1 行内代码#

4.2 代码块#

4.3 高亮指定行#

五、短代码（Shortcodes）#

5.1 figure 图片（带标题与图注）#

5.2 collapse 折叠#

5.3 note 提示框（本站增强）#

5.4 rawhtml 原始 HTML#

5.5 音频与视频#

5.6 行内小图标#

5.7 details 折叠（Hugo 原生）#

5.8 显示短代码语法本身#

六、增强语法#

6.1 行内高亮#

6.2 两栏对比#