文章 on Lumoes Blog https://blog.646474.xyz/posts/ 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/`（短代码与钩子）
]]> Hugo 博客多平台部署与 baseURL 配置 https://blog.646474.xyz/posts/multi-platform-deploy/ Wed, 07 Oct 2026 01:20:00 +0800 https://blog.646474.xyz/posts/multi-platform-deploy/ 同一份源码部署到 GitHub Pages / Vercel / Netlify / Cloudflare Pages 的配置方法，以及 baseURL 的作用与实测结论。 本站同一份源码部署在多个平台（GitHub Pages / Vercel / Netlify / Cloudflare Pages …）， 但主域名只有一个。本文档说明配置方式。

一、本站采用的方案：主域名统一

hugo.yaml 里 baseURL 填的是主域名：

baseURL: "https://blog.646474.xyz/"

所有平台都用这一个值，构建命令不需要任何额外参数。这样做的效果：

内容 实际行为
CSS / JS 资源 用相对路径（/assets/...）→ 每个平台都能正常加载
文章图片 根相对路径（/images/...）→ 同上
canonical 统一指向 https://blog.646474.xyz/...
sitemap.xml / rss.xml 统一指向主域名
分享卡片（OG / Twitter） 统一指向主域名
SEO 效果 权重集中在主域名，不存在重复内容问题
其他平台的角色 镜像 / 备用入口（访问正常，但不与主站争夺收录）

这是最省心的多平台方案：配一次，处处可用。

二、各平台配置表

平台 构建命令 输出目录 需要的环境变量
GitHub Pages hugo --gc --minify public 无（本仓库 Actions 已配好，只需 DEPLOY_TOKEN Secret）
Vercel hugo --gc --minify public HUGO_VERSION = 0.167.0
Netlify hugo --gc --minify public HUGO_VERSION = 0.167.0
Cloudflare Pages hugo --gc --minify public HUGO_VERSION = 0.167.0
其他平台 hugo --gc --minify public 视平台而定

关键：HUGO_VERSION 必须填 0.167.0，且必须是 extended 版本（PaperMod 用 SCSS，标准版会构建失败）。Cloudflare Pages 默认装的即是 extended；Vercel / Netlify 需要确认。

三、各平台详细步骤

3.1 GitHub Pages（本仓库已配置）

.github/workflows/deploy.yml：推送 main → 构建 → 推送到 666mingqing6.github.io 仓库。

只需配置一个 Secret：

名称 值
DEPLOY_TOKEN 对 666mingqing6.github.io 有写权限的 GitHub Token（经典 Token 勾 repo）

3.2 Vercel

  1. 导入 blog-hugo 仓库
  2. Framework Preset 选 Hugo
  3. Build Command：hugo --gc --minify
  4. Output Directory：public
  5. Environment Variables 加 HUGO_VERSION = 0.167.0

3.3 Netlify

  1. 导入仓库
  2. Build command：hugo --gc --minify
  3. Publish directory：public
  4. Environment 加 HUGO_VERSION = 0.167.0

如构建报 SCSS 错误，在仓库根目录加 netlify.toml：

[build]
  command = "hugo --gc --minify"
  publish = "public"

[build.environment]
  HUGO_VERSION = "0.167.0"

3.4 Cloudflare Pages

  1. 连接 Git 仓库
  2. Build command：hugo --gc --minify
  3. Build output directory：public
  4. Environment variables 加 HUGO_VERSION = 0.167.0

3.5 其他平台 / 自建服务器

hugo --gc --minify      # 构建
# 把 public/ 作为静态站点根目录部署

四、备选方案：让各平台用自己的域名

如果你希望每个平台的域名都被独立收录（例如想分别推广），可以改为在构建时覆盖 baseURL：

平台 构建命令 环境变量说明
Vercel hugo --gc --minify --baseURL "https://$VERCEL_URL/" VERCEL_URL 不含协议，需手动补 https://
Netlify hugo --gc --minify --baseURL "$URL/" URL 含协议
Cloudflare Pages hugo --gc --minify --baseURL "$CF_PAGES_URL/" CF_PAGES_URL 含协议
GitHub Pages hugo --gc --minify --baseURL "https://666mingqing6.github.io/" 无自动变量，写固定值

代价：同一内容出现在多个域名下，搜索引擎视为重复内容，权重会分散。

若采用此方案又想避免重复内容，两种补救：

  1. 只让主站被收录：其他平台的 static/robots.txt 写 
    User-agent: *
Disallow: /
  2. canonical 统一指向主域名：需要自定义 layouts/_partials/post_canonical.html， 把 .Permalink 换成主域名拼路径。

五、常见问题

现象 原因 解决
页面能打开但样式全无 极少见（PaperMod 用相对路径，一般不会） 检查平台是否正确部署了 public/ 全部内容
分享卡片链接指向主域名 正常行为（主域名统一方案） 无需处理
搜索引擎只收录主域名 正常行为 无需处理；想改见第四节
某平台构建报 SCSS 错误 装的是标准版 Hugo 设 HUGO_VERSION=0.167.0 并确认平台提供 extended
构建成功但页面是旧的 平台 CDN 缓存 平台后台清缓存
想临时用其他域名本地预览 命令行覆盖即可 hugo server --baseURL http://localhost:1313/
不确定产物里的地址对不对 构建后检查 grep -o '<link rel=canonical[^>]*>' public/posts/*/index.html | head

六、一句话总结

baseURL 固定填主域名 https://blog.646474.xyz/，所有平台共用； 资源走相对路径各平台都能显示，SEO 权重全部集中到主域名。 其他平台就是主站的镜像与备用入口。

]]> 从 Hexo(AnZhiYu) 迁移到 Hugo(PaperMod) 完整记录 https://blog.646474.xyz/posts/hexo-to-hugo-migration/ Wed, 07 Oct 2026 01:20:00 +0800 https://blog.646474.xyz/posts/hexo-to-hugo-migration/ 迁移过程中的语法对照表：哪些标签不能用、怎么替换、front matter 字段如何对应，以及踩过的坑。

一、先说结论：工作量评估

项目 说明
文章正文 需要替换标签语法（见第二、三节），每篇约 5~15 分钟
front matter 需要调整字段（见第五节），可脚本批量处理
图片 从 source/img/ 移到 static/images/，路径前缀从 /img/ 改为 /images/
特有功能 即刻短文、音乐播放器、首页轮播、AI 摘要、置顶卡片 PaperMod 都没有，需要自行实现或放弃
评论系统 需要重新接入（PaperMod 预留了 layouts/_partials/comments.html）

建议：先迁移 3~5 篇代表性文章，跑通流程后再批量处理。

二、新博客不能用的语法（AnZhiYu / Hexo 专有）

以下标签在 Hugo + PaperMod 中不存在，写上去会原样显示成文本（或报错），必须替换：

2.1 Hexo tag 插件（AnZhiYu 全部标签）

AnZhiYu 标签 能否使用 替代方案
{% note info %} {% endnote %} ❌ {{< note info >}}…{{< /note >}}（短代码，内容支持 Markdown）
{% label 文字 red %} ❌ <mark class="hl red">文字</mark>（本项目已内置样式）
{% mermaid %} {% endmermaid %} ❌ ```mermaid 代码块（本项目已配置好）
{% katex %} / {% mathjax %} ❌ $$公式$$（单行）或 {{< math >}}…{{< /math >}}（多行）
{% tabs %} / {% endtabs %} ❌ <div class="columns">…</div>（静态两栏，本项目已内置）或删除
{% checkbox %} ❌ Markdown 任务列表 - [x] 已完成
{% timeline %} ❌ 有序列表，或自建样式
{% folding %} ❌ {{< collapse "标题" >}}内容{{< /collapse >}}
{% links %} ❌ Markdown 列表 + 链接
{% btn %} / {% btns %} / {% cell %} ❌ Markdown 链接或 <a class="...">
{% tip %} ❌ <div class="note primary">…</div>
{% span %} / {% u %} / {% emp %} / {% wavy %} / {% del %} / {% kbd %} / {% psw %} ❌ 原生 HTML：<u> <em> <del> <kbd>
{% gallery %} ❌ 多张 {{< figure >}} 或用 Markdown 图片
{% hide %} ❌ {{< collapse >}}
{% image %} / {% inlineImg %} ❌ {{< figure >}} / Markdown ![]()
{% bilibili %} / {% media %} / {% dogeplayer %} ❌ {{< rawhtml >}}<iframe>…{{< /rawhtml >}}
{% site %} / {% flink %} / {% iconfont %} / {% Introduction-card %} ❌ 手写 HTML 或用 rawhtml

2.2 其它 Hexo / AnZhiYu 专有写法

写法 说明
<div class="video-container">…</div> + 配套 <style> AnZhiYu 的视频自适应写法 → 改用 {{< youtube ID >}} 或 {{< video src="…" >}}
<!-- more --> Hugo 用 `

（无空格），或在 front matter 写 summary:| |{% raw %}/{% endraw %}| Hugo 用{{< … >}}转义 shortcode | | Hexo 的_drafts/目录 | Hugo 用draft: true标记 | | 即刻短文（essay）系统 | ❌ 无对应，需自行实现（可考虑 Hugo 的独立 section） | | 音乐播放器 / APlayer | ❌ 需自行接入第三方 JS | | 首页轮播图 / 置顶卡片组 | ❌ 无对应，可用 PaperMod 的profileMode 或自建布局 | | AI 摘要（ai:字段） | ❌ 无对应，可改写到description` | | 站点统计（不蒜子等） | ❌ 需自行接入 |

2.3 不能用的 front matter 字段

swiper_index、top_group_index、cover_fit、cover_day、cover_night、ai、abbrlink、background、aside、highlight_shrink、copyright / copyright_author / copyright_url / copyright_info、aplayer、mathjax、katex、toc_number、toc_style_simple、sticky、top_img

这些字段写在 Hugo 里不会报错（被忽略），但也没有任何效果，建议清理。

三、新博客支持的语法（怎么写）

3.1 基础 Markdown（完全通用）

# 一级标题
## 二级标题

**加粗**、*斜体*、~~删除线~~、`行内代码`、[链接](https://example.com)

- 无序列表
- 第二项
  - 嵌套

1. 有序列表

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

| 表头 | 表头 |
|---|---|
| 单元格 | 单元格 |

> 引用块

---

3.2 PaperMod 自带 shortcode

语法 作用
{{< figure src="/images/a.png" title="标题" caption="说明" align="center" >}} 图片（带图注，比 Markdown 图片更精细）
{{< inTextImg url="/images/a.png" alt="说明" >}} 行内小图标
{{< collapse "点击展开" >}}内容{{< /collapse >}} 折叠面板
{{< rawhtml >}}<div>任意 HTML</div>{{< /rawhtml >}} 嵌入原始 HTML
{{< video src="/media/a.mp4" >}} 本地视频
{{< audio src="/media/a.mp3" >}} 本地音频
{{< ltr >}} / {{< rtl >}} 强制文字方向

3.3 Hugo 内置 shortcode

语法 作用
{{< youtube VIDEO_ID >}} 嵌入 YouTube（替代 AnZhiYu 的 video-container）
{{< vimeo VIDEO_ID >}} 嵌入 Vimeo
{{< gist 用户名 哈希 >}} 嵌入 GitHub Gist
{{< details "标题" >}}内容{{< /details >}} 折叠（Hugo 原生）
{{< highlight python "linenos=table" >}}代码{{< /highlight >}} 带行号的代码块
{{< ref "posts/某篇文章.md" >}} 站内链接（自动处理路径）
{{< param 参数名 >}} 读取配置参数

3.4 本项目已额外配置好的语法（实测可用）

提示框（对标 AnZhiYu 的 {% note %}，用短代码，内容支持 Markdown）：

{{< note info >}}
信息提示，支持 **加粗**、`代码`、[链接](url)
{{< /note >}}

{{< note success >}}成功提示{{< /note >}}
{{< note warning >}}警告提示{{< /note >}}
{{< note danger >}}危险提示{{< /note >}}
{{< note primary >}}重点提示{{< /note >}}

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

⚠️ 不建议用 <div class="note info"> 的 HTML 写法：块级 HTML 内部的 Markdown 不会被解析（CommonMark 规范行为），加粗会原样显示成星号。

行内高亮（对标 {% 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>

两栏对比（对标 {% tabs %} 的静态替代）：

<div class="columns">
<div>
<h4>方案 A</h4>
<p>内容…</p>
</div>
<div>
<h4>方案 B</h4>
<p>内容…</p>
</div>
</div>

数学公式（KaTeX）：

行内：$E = mc^2$

单行独立公式（推荐日常使用）：
$$E = mc^2$$

多行 / 复杂公式（矩阵、多行推导必须用这个）：
{{< math >}}
\begin{pmatrix}
a & b \\
c & d
\end{pmatrix}
{{< /math >}}

⚠️ 重要：多行公式不要直接写多行 $$——Markdown 解析器会把 \end{pmatrix} 这类行误判成标题，导致公式破损。多行公式一律用 {{< math >}} 包裹。

Mermaid 流程图（直接用代码块，无需记短代码）：

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

时序图、甘特图、类图等所有 Mermaid 图表类型都支持。

3.5 开启数学公式的两种方式

文章 front matter 里任意一种写法都会自动加载 KaTeX：

math: true          # 显式开启

或者正文里出现 $$ 也会自动检测开启。

四、推荐的创作语法组合

日常写作最有价值的四件套：

场景 推荐语法
强调重要结论 <div class="note danger">结论</div>
补充说明、可选细节 {{< collapse "展开查看" >}}…{{< /collapse >}}
流程 / 结构 / 时序 ```mermaid 代码块
公式推导 $$单行$$ 或 {{< math >}}多行{{< /math >}}
图片带说明 {{< figure src="…" caption="…" >}}
代码 普通代码块（自带高亮 + 复制按钮）
对比两种方案 <div class="columns">

五、front matter 迁移对照表

Hexo (AnZhiYu) Hugo (PaperMod) 说明
title: "标题" title: "标题" 相同
date: 2026-04-24 19:40:46 date: 2026-04-24T19:40:46+08:00 Hugo 两种格式都能解析，但推荐 ISO 8601
updated: 2026-08-08 20:40:00 lastmod: 2026-08-08T20:40:00+08:00 字段名不同
tags: [a, b] tags: ["a", "b"] 相同
categories: [[生活, 意识形态]] categories: ["生活"] Hugo 不支持多级分类，二级建议改成 tag
cover: /img/webp/94.webp cover:
image: "/images/webp/94.webp"		 结构不同（对象）
description: "…" description: "…" 相同
keywords: [a, b] keywords: ["a", "b"] 相同
abbrlink: xxx slug: xxx 自定义 URL
top: true weight: 1（越小越前） 置顶需自行实现
toc: true ShowToc: true 字段名不同
toc_number: true UseHugoToc: true 近似
comments: false comments: false 相同
hide: true hideSummary: true 近似
mathjax: true / katex: true math: true 统一为 math
swiper_index / top_group_index / ai / background / aside / cover_fit / cover_day / cover_night / copyright_* ❌ 无对应，删除即可

六、迁移操作步骤

1. 复制文章

# 在 Hexo 项目里（blog-demo/source/_posts/）
cp 某篇文章.md Z:/ugoblog/content/posts/

2. 调整 front matter

  • updated → lastmod
  • cover: /img/x.webp → cover.image: "/images/x.webp"
  • 多级 categories 拆成一维
  • 删除无对应字段

3. 替换正文标签

查找 替换为
{% note xxx %} … {% endnote %} {{< note xxx >}} … {{< /note >}}
{% label 文字 颜色 %} <mark class="hl 颜色">文字</mark>
{% mermaid %} … {% endmermaid %} ```mermaid … ```
{% tabs %} … {% endtabs %} 删除或改 <div class="columns">
{% folding 标题 %} … {% endfolding %} {{< collapse "标题" >}} … {{< /collapse >}}
<div class="video-container"> 整块 {{< youtube 视频ID >}}

4. 迁移图片

# Hexo: blog-demo/source/img/  →  Hugo: Z:/ugoblog/static/images/
cp -r blog-demo/source/img/* Z:/ugoblog/static/images/

正文里的 /img/xxx.webp 改成 /images/xxx.webp。

5. 本地预览

cd Z:/ugoblog
hugo server -D        # 含草稿预览，浏览器打开 http://localhost:1313

6. 构建发布

hugo --gc --minify    # 产物在 public/ 目录

七、常用命令速查

hugo new content posts/我的新文章.md   # 新建文章（用 archetypes/default.md 模板）
hugo server -D                         # 本地预览（含草稿）
hugo server --bind 127.0.0.1 -p 1313   # 指定端口
hugo --gc --minify                     # 构建（清理缓存 + 压缩）
hugo --gc --minify --buildFuture       # 构建含未来日期的文章
hugo list all                          # 列出所有文章及 URL
hugo config                            # 查看当前生效的完整配置

⚠️ 注意：front matter 里 date 若是未来时间，默认不会构建（buildFuture: false）， 表现为「文章明明写了却不出现在页面上」。要么改成过去时间，要么加 --buildFuture。

八、关键文件说明

文件 / 目录 作用
hugo.yaml 站点总配置（已汉化，所有配置项都有中文说明）
archetypes/default.md 新建文章的模板（已汉化）
content/posts/ 文章目录
content/search.md 搜索页（必须存在，否则搜索功能失效）
content/archives.md 归档页
assets/css/extended/custom.css 自定义样式（提示框、高亮、两栏等）
layouts/_partials/extend_head.html 注入 KaTeX / Mermaid（PaperMod 官方扩展点）
layouts/_markup/render-codeblock-mermaid.html 让 ```mermaid 输出为图表容器
layouts/_markup/render-passthrough.html 数学公式原样输出（避免被转义）
layouts/_shortcodes/math.html 多行公式 shortcode
static/images/ 图片目录（引用路径为 /images/xxx）
themes/PaperMod/ 主题本体（升级：cd themes/PaperMod && git pull）

九、迁移后的功能对照

原 AnZhiYu 功能 PaperMod 状态
文章 + 标签 + 分类 ✅ 原生支持
归档页 ✅ 原生（content/archives.md）
站内搜索 ✅ 原生（Fuse.js，已配置）
暗色模式 ✅ 原生（跟随系统 + 手动切换）
目录 TOC ✅ 原生
代码高亮 + 复制 ✅ 原生
阅读时间 / 字数 ✅ 原生
分享按钮 ✅ 原生
数学公式 ✅ 已配置（KaTeX）
Mermaid 流程图 ✅ 已配置
提示框 / 高亮 / 两栏 ✅ 已用自定义 CSS 补齐
评论 ⚠️ 需自行接入（Twikoo / Giscus / Waline）
即刻短文 ❌ 无对应
音乐播放器 ❌ 无对应
首页轮播 / 置顶卡片 ❌ 无对应
AI 摘要 ❌ 无对应
封面图 ✅ 支持（cover.image），但无「跟随主题色」等效果
]]> 写作语法速查（写法 + 效果对照） 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. 脚注内容写在这里。 ↩︎

]]> PaperMod 语法速查（示例文章） https://blog.646474.xyz/posts/syntax-demo/ Tue, 06 Oct 2026 20:00:00 +0800 https://blog.646474.xyz/posts/syntax-demo/ 这篇示例演示 Hugo + PaperMod 支持的全部写作语法，可作为迁移时的对照参考。 这是一篇语法速查示例，演示 Hugo + PaperMod 支持的全部写作语法。 迁移旧文章时，可以对照本文把 AnZhiYu 的标签替换成这里的写法。

一、基础 Markdown

普通段落、加粗、斜体、删除线、行内代码、链接。

  • 无序列表
  • 第二项
    • 嵌套项
  1. 有序列表
  2. 第二项
  • 已完成的任务
  • 未完成的任务

这是引用块，适合放金句或重要观点。

支持多段引用。

二、表格

功能 AnZhiYu 写法 PaperMod 写法
提示框 {% note info %} <div class="note info">
折叠 {% folding %} {{< collapse >}}
流程图 {% mermaid %} ```mermaid 代码块
数学公式 {% katex %} $公式$ 或 $$公式$$

三、代码块

def greet(name: str) -> str:
    """代码块会自动高亮，并带复制按钮"""
    return f"Hello, {name}!"

hugo new content posts/我的新文章.md   # 新建文章
hugo server -D                        # 本地预览（含草稿）
hugo                                  # 构建静态文件到 public/

四、提示框（用 note 短代码，内容支持 Markdown）

这是信息提示框（info）。内部支持 加粗、行内代码、链接、列表等全部 Markdown 语法。
这是成功提示框（success）
这是警告提示框（warning）
这是危险提示框（danger）
带标题的提示框：第二个参数就是标题。Markdown 依然生效。
为什么不用 HTML 写法？（点击了解）

直接写 <div class="note info">…</div> 时，块级 HTML 内部的 Markdown 不会被解析 （这是 CommonMark 规范的行为），**加粗** 会原样显示成星号。

所以本站提供 note 短代码：内容会先经过 Markdown 渲染再填入提示框。 如需用 HTML 写法，标签与内容之间必须留空行：

<div class="note info">

**加粗**会被解析

</div>

五、高亮与两栏对比

行内高亮：重点内容、正确做法、补充信息

两栏对比（并排显示，适合替代 AnZhiYu 的 tabs）：

方案 A：Hexo + AnZhiYu

标签丰富、生态成熟、上手快。适合喜欢现成组件、愿意维护插件依赖的场景。

方案 B：Hugo + PaperMod

构建极快（毫秒级）、零依赖、配置简单。适合专注内容创作、追求长期可维护性。

六、折叠内容

点击展开 / 收起

这里是被折叠的内容，适合放补充说明、长代码、参考资料。

  • 列表也可以
  • 支持任意 Markdown

七、数学公式（KaTeX）

行内公式：质能方程 E = mc^2，欧拉恒等式 e^{i\pi} + 1 = 0。

独立公式：

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

矩阵（多行公式 —— 用 math 短代码包裹，避免 Markdown 误判）：

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

矩阵（单行公式 —— 直接写 $$...$$ 即可，内容写在同一行）：

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

八、Mermaid 流程图

直接写 ```mermaid 代码块即可（本模板已自动转换，不需要记短代码）：

flowchart TD
    A[Hexo + AnZhiYu] --> B{是否长期创作?}
    B -->|是| C[迁移到 Hugo + PaperMod]
    B -->|否| D[保持现状]
    C --> E[转换 front matter]
    E --> F[替换标签语法]
    F --> G[完成迁移]

时序图也支持：

sequenceDiagram
    participant 作者
    participant Hugo
    participant 浏览器
    作者->>Hugo: 写 Markdown
    Hugo->>Hugo: 构建（毫秒级）
    Hugo->>浏览器: 输出静态 HTML
    浏览器-->>作者: 极快的访问体验

九、图片

普通 Markdown 写法（PaperMod 会自动生成图注）：

示例图片说明

更精细的控制用 figure 短代码：

图片说明文字，会显示在图下方
图片标题

图片说明文字，会显示在图下方

十、视频与音频

{{< youtube VIDEO_ID >}}                 YouTube 视频
{{< vimeo VIDEO_ID >}}                   Vimeo 视频
{{< video src="https://blog.646474.xyz/media/demo.mp4" >}}      本地视频
{{< audio src="https://blog.646474.xyz/media/demo.mp3" >}}      本地音频

十一、原始 HTML

需要写复杂 HTML（如 iframe 嵌入）时用 rawhtml 短代码：

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

以上就是全部可用语法。日常写作里最常用的组合是：提示框 + 代码块 + 数学公式 + Mermaid。

]]>