写作 on Lumoes Blog https://blog.646474.xyz/tags/%E5%86%99%E4%BD%9C/ Recent content in 写作 on Lumoes Blog Lumoes Blog https://blog.646474.xyz/images/og-cover.png https://blog.646474.xyz/images/og-cover.png Hugo zh-cn Wed, 07 Oct 2026 01:20:00 +0800 Hugo + PaperMod 写作语法大全 https://blog.646474.xyz/posts/writing-guide/ Wed, 07 Oct 2026 01:20:00 +0800 https://blog.646474.xyz/posts/writing-guide/ 本站支持的全部写作语法速查：Markdown、短代码、提示框、数学公式、Mermaid 图表，每条都有写法与示例。

目录

一、快速开始

1.1 三个命令

hugo new content posts/我的新文章.md    # 新建文章（自动套用 archetypes/default.md 模板）
hugo server -D                          # 本地预览（-D 表示包含草稿），打开 http://localhost:1313
hugo --gc --minify                      # 构建发布（产物在 public/ 目录）

1.2 一篇文章的最小结构

---
title: "文章标题"
date: 2026-10-07T10:00:00+08:00
draft: false
tags: ["标签1", "标签2"]
categories: ["分类"]
---

正文从这里开始。

1.3 写作流程建议

  1. hugo new content posts/xxx.md 新建（默认 draft: true）
  2. 写内容，浏览器开着 hugo server -D 实时预览
  3. 写完把 draft 改为 false
  4. hugo --gc --minify 构建，把 public/ 部署到托管平台

二、Front Matter 完全指南

Front matter 是文章头部的 YAML 配置块（--- 包裹）。所有字段都是可选的，不写的字段会使用 hugo.yaml 里的全局默认值。

2.1 完整字段表

---
# ===== 基础信息 =====
title: "文章标题"                    # 必需。显示在页面顶部与列表页
date: 2026-10-07T10:00:00+08:00     # 必需。发布时间（推荐 ISO 8601 格式，带时区）
lastmod: 2026-10-08T15:30:00+08:00  # 最后修改时间（会显示在页面上）
draft: false                        # true = 草稿（构建时跳过，预览需加 -D）

# ===== 描述与分类 =====
description: "文章摘要，显示在列表页、搜索结果与分享卡片"   # 建议 50~150 字
summary: "列表页摘要（留空则自动截取正文开头）"              # 可选
tags: ["哲学", "读书"]               # 标签（对应 /tags/ 页面）
categories: ["随笔"]                 # 分类（对应 /categories/ 页面，Hugo 不支持多级）
keywords: ["关键词1", "关键词2"]      # SEO 关键词
author: "Lumoes"                     # 作者（留空用全局配置）

# ===== 封面图（对象结构，注意缩进）=====
cover:
  image: "/images/cover/example.jpg"  # 图片路径（相对 static/），如放 static/images/cover/ 就写 /images/cover/xxx.jpg
  alt: "封面描述"                     # 无障碍与 SEO
  caption: "封面说明文字"              # 图片下方说明（可留空）
  relative: false                     # true = 路径相对于当前文章目录；false = 相对于 static/

# ===== 显示控制（不写则用全局默认）=====
ShowToc: true              # 显示目录
TocOpen: false             # 目录默认展开
hidemeta: false            # 隐藏日期/作者/阅读时间等元信息（适合「关于」页）
hideSummary: false         # 列表页不显示摘要
comments: true             # 显示评论区（需先接入评论系统）
ShowReadingTime: true      # 显示阅读时间
ShowWordCount: true        # 显示字数
ShowShareButtons: true     # 显示分享按钮
ShowBreadCrumbs: true      # 显示面包屑导航
ShowPostNavLinks: true     # 显示上一篇/下一篇
ShowCodeCopyButtons: true  # 代码块显示复制按钮
hideFooter: false          # 隐藏页脚

# ===== 功能开关 =====
math: true                 # 开启数学公式（正文出现 $$ 也会自动开启，可省略）
searchHidden: true         # 从站内搜索中排除本文
robotsNoIndex: true        # 让搜索引擎不收录本文
slug: "custom-url"         # 自定义 URL（默认用文件名）

# ===== 编辑链接（可选）=====
editPost:
  URL: "https://github.com/你/仓库/content"
  Text: "编辑此页"
  appendFilePath: true
---

2.2 三种常用组合

普通文章（大多数情况）：

---
title: "文章标题"
date: 2026-10-07T10:00:00+08:00
draft: false
tags: ["标签"]
categories: ["随笔"]
description: "一句话摘要"
cover:
  image: "/images/cover/x.jpg"
---

静态页面（关于、友链等，无日期无目录）：

---
title: "关于"
url: "/about/"
ShowToc: false
hidemeta: true
comments: false
---

技术长文（开目录、开公式）：

---
title: "深入理解 XXX"
date: 2026-10-07T10:00:00+08:00
tags: ["技术"]
categories: ["技术"]
ShowToc: true
TocOpen: true
math: true
---

2.3 字段优先级

同一个字段可以写在三处，优先级从高到低：

  1. 文章 front matter（最高，覆盖下面两者）
  2. hugo.yaml 的 params（站点默认值）
  3. 主题内部默认值（最低）

例如：全局 ShowToc: true，某篇文章想关掉就写 ShowToc: false。

三、Markdown 基础语法

3.1 标题

# 一级标题（一般不用，文章标题已是一级）
## 二级标题
### 三级标题
#### 四级标题
##### 五级标题
###### 六级标题

目录（TOC）默认只收录 二级到四级 标题（可在 hugo.yaml 的 markup.tableOfContents 调整）。

3.2 文本样式

**加粗**
*斜体*
***粗斜体***
~~删除线~~
`行内代码`
普通文字

效果：加粗、斜体、粗斜体、删除线、行内代码

3.3 列表

- 无序项
- 无序项
  - 嵌套项（缩进 2 空格）
    - 更深嵌套（缩进 4 空格）

1. 有序项
2. 有序项
   1. 嵌套有序

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

任务列表在 PaperMod 里会渲染成复选框样式，很适合写「清单」「进度」。

3.4 引用

> 单行引用

> 多段引用第一段
>
> 多段引用第二段

> 引用中嵌套引用
>
> > 第二层引用

> **引用里也支持 Markdown**，比如**加粗**和[链接](https://example.com)

3.5 代码

行内代码：用反引号包裹，如 const a = 1

代码块：三个反引号 + 语言名（会有语法高亮和复制按钮）

```python
def hello(name):
    return f"Hello, {name}"
```

```javascript
const greet = (name) => `Hello, ${name}`;
```

```bash
hugo server -D
```

```text
没有语法高亮的纯文本块（画 ASCII 图、贴日志时用）
```

支持的语言名（部分）：python javascript typescript java go rust c cpp csharp php ruby sql bash shell powershell yaml json toml xml html css scss markdown text diff nginx dockerfile

3.6 链接

[显示文字](https://example.com)
[带标题的链接](https://example.com "鼠标悬停显示的文字")

<!-- 站内链接（推荐用 ref，路径改了也不会失效）-->
[看这篇文章]({{< ref "posts/syntax-demo.md" >}})

<!-- 锚点跳转 -->
[跳到本页某节](#三markdown-基础语法)

直接写裸链接也会自动变成可点击的链接：https://example.com

3.7 图片

<!-- 基础写法（PaperMod 会自动把 alt 显示为图注）-->
![图片说明](/images/example.png)

<!-- 带链接的图片 -->
[![图片说明](/images/example.png)](https://example.com)

图片放在 static/images/ 目录下，引用路径写 /images/xxx.png 需要更精细控制（标题、图注、对齐）请用 figure 短代码（见 4.1）

3.8 表格

| 左对齐 | 居中 | 右对齐 |
|:---|:---:|---:|
| 内容 | 内容 | 内容 |
| 内容 | 内容 | 内容 |

效果：

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

3.9 分割线

---

⚠️ 注意：--- 前后要空一行，否则可能被误解析为标题下划线或 front matter。

3.10 脚注

这句话有个脚注[^1]，还有另一个[^note]。

[^1]: 这是第一个脚注的内容。
[^note]: 脚注名可以是文字，会自动编号。

3.11 转义字符

需要显示 Markdown 符号本身时，在前面加反斜杠：

\* 这不是斜体 \*
\# 这不是标题
\[方括号\] 不是链接

3.12 内联 HTML

本站在 hugo.yaml 里开启了 unsafe: true，所以可以直接在正文里写 HTML：

<span style="color: #ef4444;">红色文字</span>
<u>下划线</u>
<kbd>Ctrl</kbd> + <kbd>C</kbd>
<abbr title="HyperText Markup Language">HTML</abbr>
<br>
<div style="text-align: center;">居中内容</div>

这是本站「提示框」「高亮」「两栏」等增强语法的实现基础（见第六节）。

3.13 原生折叠（HTML details）

不需要短代码的折叠写法：

<details>
<summary>点击展开</summary>

这里是被折叠的内容，**支持 Markdown**。

</details>

推荐用 collapse 短代码（见 4.3），样式更统一。

四、PaperMod 主题短代码

短代码（shortcode）是 Hugo 的特殊语法，格式为 {{< 名称 参数 >}}，由主题/站点模板渲染成 HTML。

4.1 figure 图片（最常用）

<!-- 最简 -->
{{< figure src="https://blog.646474.xyz/images/example.png" >}}

<!-- 完整参数 -->
{{< figure
  src="https://blog.646474.xyz/images/example.png"
  title="图片标题"
  caption="图片说明文字，支持 **Markdown**"
  alt="无障碍描述"
  width="600"
  height="400"
  align="center"
  class="custom-class"
  link="https://example.com"
  target="_blank"
  rel="noopener"
>}}
参数 说明
src 图片路径（必需），如 /images/x.png
title 图片上方的标题
caption 图片下方的说明（支持 Markdown）
alt 无障碍描述（留空则用 caption）
width / height 尺寸（像素）
align 设为 center 可居中显示
link 点击图片跳转的链接
target / rel 链接的打开方式与安全属性
class 自定义 CSS 类

4.2 inTextImg 行内小图

适合在文字中插入小图标（如徽章、状态标识）：

本站使用 {{< inTextImg url="https://blog.646474.xyz/images/logo.svg" alt="logo" height="20" >}} 作为站点图标。
参数 说明
url 图片路径（必需）
alt 替代文字
height 高度（默认 15px）

4.3 collapse 折叠

{{< collapse summary="点击展开 / 收起" >}}
这里是被折叠的内容，支持任意 Markdown。

- 列表
- **加粗**
{{< /collapse >}}

<!-- 默认展开 -->
{{< collapse summary="默认展开的面板" openByDefault=true >}}
内容…
{{< /collapse >}}
参数 说明
summary 折叠标题（必须用命名参数写法 summary="标题"）
openByDefault true = 默认展开

⚠️ 必须写 summary="标题"，写成位置参数 {{< collapse "标题" >}} 会报警告且标题为空。

4.4 rawhtml 原始 HTML

包裹需要原样输出的 HTML（避免被 Markdown 处理）：

{{< rawhtml >}}
<div class="my-widget">
  <iframe src="https://example.com/embed" width="100%" height="400"></iframe>
</div>
{{< /rawhtml >}}

本站已开启 unsafe: true，简单 HTML 可直接写；遇到被 Markdown 干扰的复杂结构时用这个包裹。

4.5 audio / video 本地媒体

{{< audio src="https://blog.646474.xyz/media/demo.mp3" >}}

{{< video src="https://blog.646474.xyz/media/demo.mp4" >}}

文件放在 static/media/ 下。音频/视频默认静音（muted），点击播放器可取消静音。

4.6 ltr / rtl 文字方向

{{< ltr >}}
这段文字强制从左到右显示
{{< /ltr >}}

{{< rtl >}}
这段文字强制从右到左显示（阿拉伯语等）
{{< /rtl >}}

<!-- 内容需要渲染 Markdown 时加 md=true -->
{{< ltr md=true >}}
**加粗**会被渲染
{{< /ltr >}}

五、Hugo 内置短代码

这些是 Hugo 自带的能力（无需主题支持）。

5.1 youtube / vimeo 视频嵌入

{{< youtube i8Iiv9yFTdM >}}          <!-- YouTube 视频 ID -->

{{< youtube id="i8Iiv9yFTdM" title="视频标题" autoplay="false" >}}

{{< vimeo 123456789 >}}                <!-- Vimeo 视频 ID -->

视频 ID 是 URL 里的那串字符：https://www.youtube.com/watch?v=i8Iiv9yFTdM → i8Iiv9yFTdM

5.2 gist 代码片段

{{< gist 用户名 哈希值 >}}
{{< gist 用户名 哈希值 文件名 >}}

5.3 details 折叠（Hugo 原生）

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

{{< details summary="也可以这样写" open=true >}}
内容…
{{< /details >}}

与 PaperMod 的 collapse 功能相同，选一个用即可（collapse 样式与主题更统一）。

5.4 highlight 代码高亮（精细控制）

{{< highlight python "linenos=table,hl_lines=2-3,linenostart=1" >}}
def hello():
    print("这行会高亮")
    print("这行也会高亮")
{{< /highlight >}}
参数 说明
linenos=table 显示行号
hl_lines=2-3 高亮第 2~3 行
linenostart=1 行号起始值

日常写作直接用普通代码块即可（自动高亮），需要高亮特定行时才用这个。

5.5 ref / relref 站内链接

[看这篇文章]({{< ref "posts/syntax-demo.md" >}})
[同上，相对链接]({{< relref "posts/syntax-demo.md" >}})

好处：文章改名/移动后链接自动更新，不会 404。强烈推荐站内跳转用这个。

5.6 param 读取配置

本站作者是 {{< param author >}}，标题是 {{< param title >}}。

读取 hugo.yaml 里 params 下的字段值。

5.7 qr 二维码

{{< qr text="https://example.com" >}}
{{< qr text="https://example.com" level="h" scale="4" >}}

5.8 短代码转义（显示而非执行）

想在文章里展示短代码语法本身（而不是执行它），用 /* */ 包裹：

{{< figure src="https://blog.646474.xyz/images/x.png" >}}      → 页面显示 {{< figure src="https://blog.646474.xyz/images/x.png" >}}
{{< youtube abc123 >}}                   → 页面显示 {{< youtube abc123 >}}

六、本站增强语法

以下语法由本站在 assets/css/extended/custom.css 与 layouts/ 中额外配置，AnZhiYu 的对应标签都可用它们替代。

6.1 提示框（替代 {% note %}）

用 note 短代码（内容会经过 Markdown 渲染）：

{{< note info >}}蓝色信息提示{{< /note >}}
{{< note success >}}绿色成功提示{{< /note >}}
{{< note warning >}}黄色警告提示{{< /note >}}
{{< note danger >}}红色危险提示{{< /note >}}
{{< note primary >}}紫色重点提示{{< /note >}}

带标题（第二个参数）：
{{< note warning "注意" >}}
带自定义标题的提示框
{{< /note >}}

内容支持全部 Markdown：
{{< note info >}}
**加粗**、`行内代码`、[链接](https://example.com)、列表都可以。
{{< /note >}}

⚠️ 不要用 <div class="note info">…</div> 的 HTML 写法：块级 HTML 内部的 Markdown 不会被解析（CommonMark 规范行为），**加粗** 会原样显示成星号。 如确要用 HTML 写法，标签与内容之间必须留空行。

6.2 行内高亮（替代 {% label %}）

<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>
<mark class="hl">默认色</mark>

实际效果：红色重点、绿色、蓝色、黄色、紫色

6.3 两栏对比（替代 {% tabs %}）

<div class="columns">
<div>
<h4>方案 A</h4>
<p>内容…</p>
</div>
<div>
<h4>方案 B</h4>
<p>内容…</p>
</div>
</div>
  • 宽屏并排两栏，窄屏自动堆叠
  • 三栏及以上也可以（自动换行）
  • 这是静态对比（不像 tabs 可点击切换）

6.4 数学公式（KaTeX）

<!-- 行内公式 -->
质能方程 $E = mc^2$ 是狭义相对论的核心。

<!-- 单行独立公式（推荐日常使用）-->
$$\int_{-\infty}^{+\infty} e^{-x^2} \, dx = \sqrt{\pi}$$

<!-- 多行 / 复杂公式：必须用 math 短代码包裹 -->
{{< math >}}
\begin{pmatrix}
a & b \\
c & d
\end{pmatrix}
\begin{pmatrix}
x \\
y
\end{pmatrix}
=
\begin{pmatrix}
ax + by \\
cx + dy
\end{pmatrix}
{{< /math >}}

<!-- 行内公式的短代码写法（需要显式指定 inline）-->
{{< math inline >}}a^2 + b^2 = c^2{{< /math >}}

支持的语法：分数 \frac{a}{b}、上下标 x^2 a_1、根号 \sqrt{x}、求和 \sum_{i=1}^{n}、积分 \int_a^b、希腊字母 \alpha \beta \pi、矩阵 \begin{pmatrix}、多行对齐 \begin{aligned}、分段函数 \begin{cases} 等（完整语法见 KaTeX 支持列表）

⚠️ 多行公式必须用 {{< math >}} 包裹，直接写多行 $$ 会被 Markdown 解析器破坏。

6.5 Mermaid 图表

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

流程图：

```mermaid
flowchart TD
    A[开始] --> B{条件判断}
    B -->|满足| C[执行操作]
    B -->|不满足| D[结束]
    C --> D
```

时序图：

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

类图：

```mermaid
classDiagram
    class Animal {
        +String name
        +eat()
    }
    class Dog {
        +bark()
    }
    Animal <|-- Dog
```

状态图：

```mermaid
stateDiagram-v2
    [*] --> 待处理
    待处理 --> 处理中
    处理中 --> 已完成
    已完成 --> [*]
```

甘特图：

```mermaid
gantt
    title 项目排期
    dateFormat YYYY-MM-DD
    section 阶段一
    需求分析 :a1, 2026-10-01, 7d
    设计     :a2, after a1, 5d
```

饼图：

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

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

6.6 组合使用示例

一段技术说明可以这样组合：

<div class="note warning" data-title="前置条件">
使用前请先安装 **Hugo extended** 版本。
</div>

处理流程如下：

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

核心算法：

T(n) = 2T(n/2) + O(n)
展开查看完整代码 
def merge_sort(arr):
    if len(arr) <= 1:
        return arr
    mid = len(arr) // 2
    return merge(merge_sort(arr[:mid]), merge_sort(arr[mid:]))
```

七、写作工具与工作流

7.1 编辑器推荐

工具 适合场景 说明
VS Code 主力写作 装 Hugo / Markdown All in One / Markdown Preview Enhanced 插件；可开终端跑 hugo server
Typora 沉浸写作 所见即所得，但需注意：它渲染的 HTML 与实际站点有差异（短代码不支持预览）
Obsidian 知识管理 适合先在库里写，再导出到 content/posts/；双链语法需改成 Hugo 的 ref
任何文本编辑器 应急 因为全是纯文本 Markdown

推荐组合：VS Code 写 + 浏览器开 http://localhost:1313 实时看效果（hugo server 会热重载）。

7.2 图片处理

  • 存放位置：static/images/，引用路径 /images/xxx.png
  • 格式建议：优先 WebP（体积小）或 PNG（需要透明时）
  • 封面裁剪：首页/列表封面建议统一比例，可用裁剪工具处理后再放入 static/images/cover/
  • 图片优化：Hugo 支持图片处理（缩放/裁剪/格式转换），需要时可研究 resources 目录

7.3 命令速查

hugo new content posts/文章名.md          # 新建文章
hugo new content about.md                # 新建页面
hugo server -D                           # 预览（含草稿）
hugo server -D --bind 0.0.0.0            # 允许局域网访问（手机上看效果）
hugo server --navigateToChanged          # 编辑后自动跳转到改动页面
hugo --gc --minify                       # 构建（清理 + 压缩）
hugo --gc --minify --buildFuture         # 构建含未来日期的文章
hugo list all                            # 列出所有文章及 URL
hugo list drafts                         # 列出草稿
hugo config                              # 查看生效的完整配置
hugo new theme 主题名                     # 创建新主题（一般用不到）

7.4 发布流程

  1. hugo --gc --minify 构建
  2. 把 public/ 目录部署到托管平台（GitHub Pages / Cloudflare Pages / Vercel / Netlify）
  3. 推荐配置 CI：推送到 Git 后自动构建部署（Cloudflare Pages 可直接连仓库，构建命令 hugo --gc --minify，输出目录 public）

注意：themes/PaperMod 是用 git clone 装的，如果主仓库也要版本管理，建议把它作为 git submodule 或直接删除 .git 目录后纳入主仓库。

八、实战：完整文章示例

以下是一篇完整文章的骨架，涵盖了常用语法：

---
title: "深入理解 XXX"
date: 2026-10-07T10:00:00+08:00
lastmod: 2026-10-07T10:00:00+08:00
draft: false
description: "本文从 A 出发，推导出 B，并给出实践建议。"
tags: ["技术", "算法"]
categories: ["技术"]
keywords: ["XXX", "算法"]
math: true
ShowToc: true
TocOpen: false
cover:
  image: "/images/cover/xxx.jpg"
  alt: "封面"
  caption: "图片来源：xxx"
---

## 背景

XXX 是一个常见问题。研究表明，**关键因素有三个**：

1. 因素一
2. 因素二
3. 因素三

<div class="note info" data-title="前置知识">
阅读本文需要了解 <mark class="hl blue">线性代数</mark> 基础。
</div>

## 核心推导

设输入为 $x$，则输出为：

$$y = \sum_{i=1}^{n} w_i x_i + b$$

多行推导：

{{< math >}}
\begin{aligned}
L &= \frac{1}{2}(y - \hat{y})^2 \\
\frac{\partial L}{\partial w_i} &= (y - \hat{y}) x_i
\end{aligned}
{{< /math >}}

## 流程图

```mermaid
flowchart TD
    A[输入数据] --> B{数据是否完整?}
    B -->|是| C[特征提取]
    B -->|否| D[数据清洗]
    D --> C
    C --> E[模型训练]
    E --> F[输出结果]

两种方案对比

方案 A：简单直观

实现快，适合数据量小的场景。缺点是扩展性差。

方案 B：复杂但可扩展

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

参考实现

def solve(x, w, b):
    return sum(wi * xi for wi, xi in zip(w, x)) + b
展开查看完整代码（含边界处理） 
def solve(x, w, b):
    if not x or len(x) != len(w):
        raise ValueError("维度不匹配")
    return sum(wi * xi for wi, xi in zip(w, x)) + b

小结

核心结论：**XXX 的关键在于 YYY**。

参考：官方文档


---

## 九、常见坑与排查

| 现象 | 原因 | 解决 |
|---|---|---|
| 文章写了但不显示 | `date` 是未来时间（`buildFuture: false`） | 改成过去时间，或构建加 `--buildFuture` |
| 文章写了但不显示 | `draft: true` | 预览用 `hugo server -D`，发布前改成 `false` |
| 多行公式显示成乱码/标题 | 直接写了多行 `$$…$$` | 用 `{{< math >}}…{{< /math >}}` 包裹 |
| 公式显示为原始 LaTeX | KaTeX 加载失败或语法错误 | 检查 front matter 的 `math: true`；检查公式语法（`throwOnError: false` 会显示原文） |
| Mermaid 显示为代码块 | 代码块语言名写错 | 必须是 `mermaid`（全小写） |
| `collapse` 没有标题 | 用了位置参数 | 改成 `collapse summary="标题"` 的命名参数写法 |
| 短代码被当成文字显示 | 尖括号缺失或参数格式错误 | 检查写法；需要展示语法本身时用转义写法（见「短代码转义」一节） |
| 图片不显示 | 路径错误 | 图片放 `static/images/`，引用写 `/images/xxx.png`（**不要**带 `static`） |
| 图片不显示 | 文件名大小写不符 | 部署到 Linux 服务器时大小写敏感 |
| 分类链接 404 | 分类名与已有分类不一致 | 统一分类命名 |
| 表格没渲染 | 分隔行缺少或格式错误 | 表格第二行必须是 `|---|---|` |
| HTML 被显示为文字 | `unsafe` 被关闭 | 确认 `hugo.yaml` 里 `markup.goldmark.renderer.unsafe: true` |
| 中文标题 URL 很长 | 默认用标题生成 | 在 front matter 加 `slug: "english-name"` |

---

## 十、速查表

### 10.1 语法一览

| 需求 | 语法 |
|---|---|
| 加粗 / 斜体 / 删除线 | `**粗**` / `*斜*` / `~~删~~` |
| 行内代码 | `` `code` `` |
| 代码块 | ` ```python ` … ` ``` ` |
| 链接 | `[文字](url)` |
| 站内链接 | `[文字]({{< ref "posts/x.md" >}})` |
| 图片 | `![说明](/images/x.png)` |
| 图片（带图注） | `{{< figure src="/images/x.png" caption="说明" >}}` |
| 表格 | `\| a \| b \|` + `\|---\|---\|` |
| 任务列表 | `- [x] 完成` |
| 引用 | `> 文字` |
| 脚注 | `文字[^1]` + `[^1]: 内容` |
| 分割线 | `---`（前后空行） |
| 提示框 | `<div class="note info">…</div>` |
| 高亮 | `<mark class="hl red">…</mark>` |
| 两栏 | `<div class="columns"><div>…</div><div>…</div></div>` |
| 折叠 | `{{< collapse summary="标题" >}}…{{< /collapse >}}` |
| 行内公式 | `$公式$` |
| 单行公式 | `$$公式$$` |
| 多行公式 | `{{< math >}}…{{< /math >}}` |
| 流程图 | ` ```mermaid ` + `flowchart TD` |
| YouTube | `{{< youtube 视频ID >}}` |
| 本地视频 | `{{< video src="/media/x.mp4" >}}` |
| 本地音频 | `{{< audio src="/media/x.mp3" >}}` |
| 原始 HTML | `{{< rawhtml >}}…{{< /rawhtml >}}` |
| 行内小图 | `{{< inTextImg url="/images/x.svg" >}}` |
| 显示短代码语法 | `{{< 短代码 >}}` |
| 自定义 URL | front matter 里 `slug: "xxx"` |

### 10.2 常用组合模板

**技术文章**：front matter（`math: true`、`ShowToc: true`）+ 提示框（前置条件）+ Mermaid（流程）+ 代码块 + 折叠（完整代码）

**思辨文章**：front matter（`categories: ["随笔"]`）+ 引用块（金句）+ 提示框（核心论点）+ 两栏（对比）+ 高亮（关键词）

**教程文章**：front matter + 有序列表（步骤）+ 代码块 + 提示框（注意事项）+ 折叠（补充说明）

---

> **文档维护**：新增语法或修改样式后，请同步更新本文档。
> **相关文件**：`hugo.yaml`（配置）、`assets/css/extended/custom.css`（样式）、`layouts/`（短代码与钩子）
]]> 写作语法速查（写法 + 效果对照） https://blog.646474.xyz/posts/writing-guide-demo/ Wed, 07 Oct 2026 00:50:00 +0800 https://blog.646474.xyz/posts/writing-guide-demo/ 每条语法都给出「怎么写」和「长什么样」的对照，照着抄即可。 本文档列出本站支持的全部写作语法，每条都给出「写法」与「实际效果」对照，方便直接照着抄。

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

一、快速开始

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

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

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

hugo server -D

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

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

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

写法：

---
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 标题

写法：

## 二级标题
### 三级标题
#### 四级标题

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

3.2 文本样式

写法：

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

效果：

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

3.3 列表

写法：

- 无序项
- 无序项
  - 嵌套项（缩进 2 空格）

1. 有序项
2. 有序项

效果：

  • 无序项
  • 无序项
    • 嵌套项
  1. 有序项
  2. 有序项

3.4 任务列表

写法：

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

效果：

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

3.5 引用

写法：

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

效果：

引用文字，支持 Markdown。

第二段。

3.6 表格

写法：

| 左对齐 | 居中 | 右对齐 |
|:---|:---:|---:|
| 内容 | 内容 | 内容 |

效果：

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

3.7 分割线

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

---

效果：

3.8 脚注

写法：

这句话有脚注[^1]。

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

效果：

这句话有脚注1。

3.9 链接

写法：

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

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

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

3.10 图片

写法：

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

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

四、代码

4.1 行内代码

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

4.2 代码块

写法：

```python
def hello(name):
    return f"Hello, {name}"
```

效果：

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

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

4.3 高亮指定行

写法：

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

效果：

1
2

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

五、短代码（Shortcodes）

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

写法：

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

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

5.2 collapse 折叠

写法：

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

效果：

点击展开

折叠里的内容，支持 Markdown。

  • 列表也行
  • 代码块也行

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

5.3 note 提示框（本站增强）

写法：

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

五种类型：

info —— 一般信息提示
success —— 成功 / 推荐做法
warning —— 注意事项
danger —— 危险 / 强烈警告
primary —— 重点强调

带标题（第二个参数）：

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

效果：

需要先安装 Hugo extended 版本。

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

5.4 rawhtml 原始 HTML

写法：

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

5.5 音频与视频

写法：

{{< audio src="https://blog.646474.xyz/media/demo.mp3" >}}
{{< video src="https://blog.646474.xyz/media/demo.mp4" >}}
{{< youtube i8Iiv9yFTdM >}}

5.6 行内小图标

写法：

{{< inTextImg url="https://blog.646474.xyz/images/logo.svg" alt="logo" height="20" >}}

5.7 details 折叠（Hugo 原生）

写法：

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

效果：

Details

内容，支持 Markdown。

5.8 显示短代码语法本身

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

写法：

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

页面效果：会原样显示成

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

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

六、增强语法

6.1 行内高亮

写法：

<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 两栏对比

写法：

<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

单行独立公式 —— 写法：

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

效果：

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

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

{{< 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 图表

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

流程图 —— 写法：

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

效果：

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

时序图 —— 写法：

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

效果：

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

饼图 —— 写法：

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

效果：

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

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

七、常用组合

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

写法：

{{< note warning "前置条件" >}}
需要 **Hugo extended** 版本。
{{< /note >}}

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

核心公式：

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

**效果**：



需要 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
短代码被当成文字显示 参数格式错误 检查尖括号与引号

九、更多

  1. 脚注内容写在这里。 ↩︎

]]>