本文档定义了博客中技术文章（content/posts/tech/）的 Markdown 格式规约，确保 KaTeX 数学公式、Mermaid 图表和常规内容在 Hugo PaperMod 主题中正确渲染。
1. Front Matter 规范
---
title: "文章标题"
date: YYYY-MM-DDTHH:MM:SS+08:00
lastmod: YYYY-MM-DDTHH:MM:SS+08:00
author: ["GopherDing"]
keywords: []
categories: []
tags:
- Tag1
- Tag2
description: "一句话描述。"
weight:
slug: ""
draft: false
comments: true
reward: false
mermaid: true # 有 mermaid 图表时设为 true
showToc: true
TocOpen: true
hidemeta: false
disableShare: true
showbreadcrumbs: true
cover:
image: ""
caption: ""
alt: ""
relative: false
---
要点：
mermaid: true仅在文章包含 mermaid 代码块时设置，否则设为false，避免不必要的 JS 加载description必须填写，用于搜索引擎和文章列表展示
2. 结构与标题
2.1 标题层级
- 不要使用一级标题 (
#)：Hugo 会自动将 Frontmatter 中的title渲染为页面一级标题，正文从 二级标题 (##) 开始 - 层级递进：遵循
##→###→####，不要跳级（例如从##直接跳到####）
正确示例：
## 1. 背景介绍
### 1.1 问题描述
#### 1.1.1 详细说明
错误示例：
# 背景介绍 (不要在正文中用一级标题)
### 1.1 问题描述 (跳过了二级标题)
2.2 标题编号风格
- 技术类统一阿拉伯数字：
tech和blog目录使用1.、2.风格- 正确：
## 1. 背景/### 2. 方案对比 - 错误：
## 一、背景/### 二、方案对比
- 正确：
- 非技术类保持一致：可用中文序号，但同一篇文章内保持一致
2.3 标题样式
- 标题不加粗：标题自带粗体，不要额外使用
**或__- 正确：
## 核心概念 - 错误：
## **核心概念**
- 正确：
- 简洁明了：标题应简练概括本节内容，避免长句
2.4 禁止伪标题
- 不要用加粗当标题：正文中
**关键概念**不会进入目录- 正确：
### 关键概念 - 错误：
**关键概念**
- 正确：
3. 段落与间距
3.1 段落空行
- 段落之间保留一行空行
3.2 段落首行缩进
- 使用全角空格：首行缩进用两个全角空格（U+3000）
- 正确：
这是首行缩进示例。
- 正确：
- 不要用半角空格：半角空格可能被 Markdown 解析为代码块或被压缩
- 替代写法：必要时可以使用 HTML 实体
　表示全角空格
3.3 块级元素间距
- 标题、代码块、分割线前后留空行：避免渲染错乱
- 引用块与列表：引用和列表前后留空行更清晰
4. 全角与半角
- 中文标点用全角：逗号、句号、冒号、引号、括号等统一使用全角
- 正确：
这是中文，使用全角标点。 - 错误：
这是中文, 使用半角标点.
- 正确：
- 英文与数字用半角：英文单词、数字、技术名词使用半角字符
- 正确：
Go 1.22/HTTP/2/Redis - 错误：
Ｇｏ １．２２
- 正确：
- 中英文混排空格：中文与英文、中文与数字之间保留半角空格
- 正确：
使用 Go 编写服务/版本 1.2 - 错误：
使用Go编写服务/版本1.2
- 正确：
5. 强调与行内语法
- 粗体 (
**text**)：用于强调关键概念或重点结论，不要滥用 - 粗体中避免括号内容：粗体内含括号时，括号及括号内内容应移到粗体外，无论括号内是中文还是英文。括号可能导致 Hugo 渲染异常
- 正确：
**不足训练**（undertrained）的大模型 - 错误：
**不足训练（undertrained）**的大模型 - 正确：
**第二步：反向传播**（从右往左） - 错误：
**第二步：反向传播（从右往左）**
- 正确：
- 禁止使用 emoji：正文中不要使用 emoji 字符（如 ✓、✗、✅、⭐ 等），用文字替代
- 正确：
支持/不支持/可见/隐藏 - 错误：
✅/✗/⭐
- 正确：
- 行内代码 (
`text`)：用于标记代码片段、文件名、路径、配置项或专有名词- 正确：请修改
config.yml文件 - 错误：请修改 config.yml 文件
- 正确：请修改
6. 数学公式（KaTeX）
6.1 行内公式
用单个 $ 包裹，不要有空格紧贴 $ 符号：
损失函数 $L$ 对权重 $W$ 的梯度为 $\frac{\partial L}{\partial W}$。
正确：$x^2$、$\alpha + \beta$
错误：$ x^2 $（$ 旁有空格会导致渲染失败）
6.2 独立公式块
用 $$ 独占一行包裹，不要在公式内使用 # 注释：
$$
\begin{aligned}
h_1 &= \tanh(W_h \cdot h_0 + W_x \cdot x_1 + b) \\
h_2 &= \tanh(W_h \cdot h_1 + W_x \cdot x_2 + b)
\end{aligned}
$$
正确：用 \text{注释文字} 或 \quad \text{（说明）} 在公式内加说明
错误：在 $$ 块内写 # 这是注释（# 会被 KaTeX 解析为颜色代码）
6.3 公式与中文注释的正确搭配方式
方式一：公式后用列表说明（推荐）
$$
\begin{aligned}
h_1 &= \tanh(W_h \cdot h_0 + W_x \cdot x_1 + b) \\
h_2 &= \tanh(W_h \cdot h_1 + W_x \cdot x_2 + b)
\end{aligned}
$$
- $h_1$：读第 1 个词，产生记忆
- $h_2$：读第 2 个词，结合记忆产生新状态
方式二：在公式内用 \text{} 包裹中文
$$
y = F(x) + x \quad \text{（残差连接）}
$$
6.4 特殊字符转义
Hugo 的 Goldmark 解析器会在 KaTeX 之前处理 Markdown，这意味着 $$ 块内的某些字符会被误认为 HTML 标签或 Markdown 语法。
尖括号 < 必须转义为 \lt
$$ 块内 < 后紧跟字母时，会被 Hugo 解析为 HTML 标签。例如 x_{<i} 中的 <i> 会被认为是 HTML 斜体标签，导致公式渲染失败。
错误：$$ p(x_t \mid x_{<t}) $$（<t> 不会被识别为 HTML，但 <i> 会；为一致性建议全部转义）
正确：$$ p(x_t \mid x_{\lt t}) $$
需要转义的常见场景：
$x_{<t}$→$x_{\lt t}$（条件概率中的"前 t 个 token"）$x_{<i}$→$x_{\lt i}$（索引约束）$a < b$→$a \lt b$（不等式）
不需要转义的情况：$a \leq b$、$a \le b$、\left( \right) 等以 \ 开头的命令中的 < 不受影响。
井号 # 不可用于注释
$$ 块内 # 会被 KaTeX 解析为颜色代码（如 #FF0000），而非注释符号。需要用 \text{注释文字} 替代。
6.5 禁止事项
| 错误写法 | 问题 | 正确写法 |
|---|---|---|
$$ 中文文字 $$ | 非 LaTeX 内容放在 $$ 内 | 用 \(公式\) 或普通文本 |
$$ x # 注释 $$ | # 被解析为颜色 | 用 \text{注释} |
$$ x_{<i} $$ | <i> 被 Hugo 解析为 HTML 标签 | $$ x_{\lt i} $$ |
$x $ | $ 旁有空格 | $x$ |
表格中 $P(A|B)$ | | 被 Markdown 解析为列分隔符 | $P(A \mid B)$ 用 \mid 替代 |
7. Mermaid 图表
7.1 基本语法
```mermaid
flowchart TD
A[开始] --> B[处理]
B --> C[结束]
```
7.2 节点标签引号规则
当标签包含以下字符时，必须用双引号包裹：
- 全角括号：
（） - 全角冒号：
： - 斜杠：
/ - 问号：
？ - HTML 标签：
<br/>
```mermaid
flowchart TD
A["PEFT参数高效微调"] 正确：全角括号，加引号
B[RMSNorm] 正确：无特殊字符，无需引号
C["量化 + LoRA"] 正确：有特殊字符，加引号
```
7.3 Edge 标签引号规则
```mermaid
flowchart TD
A -->|"归一化改进"| B 正确
A -->|为什么需要微调？| C 错误：全角问号需引号
A -->|"为什么需要微调？"| C 正确
```
7.4 禁止事项
| 错误写法 | 问题 | 正确写法 |
|---|---|---|
A[LoRA⭐] | emoji 导致语法错误 | A[LoRA]（删除 emoji） |
A[量化（4-bit）] | 全角括号未引用 | A["量化（4-bit）"] |
| `–> | 为什么？ | ` |
A[文本<br/>换行] | HTML 标签需在引号内 | A["文本<br/>换行"] |
8. 代码块规范
8.1 代码块用途分类
| 用途 | 语言标记 | 示例 |
|---|---|---|
| Python 代码 | ```python | import torch |
| Shell/Bash 命令 | ```bash | pip install torch |
| 数学推导过程 | 无标记 ``` | ∂L/∂z₂ = z₂ - y |
| 伪代码/数据流 | 无标记 ``` | 输入 → [层] → 输出 |
| 概念解释/类比 | 无标记 ``` | 多行纯文本说明 |
| 流程图/依赖图 | ```mermaid | flowchart TD |
8.2 代码块必须指定语言标识符
所有代码块必须指定语言标识符（仅数学推导、伪代码、概念解释等纯文本内容除外）：
```python
console.log("Hello");
```
8.3 什么时候用代码块 vs 正文
- 代码块：实际代码、命令、数学推导步骤、数据流图、多行概念解释
- 正文：单句说明、理论解释、类比描述
- 表格：对比数据、参数列表、模型对比
8.4 不要用代码块的情况
- 不要用代码块包裹 ASCII 表格 → 改用 Markdown 表格
- 不要用代码块包裹 Mermaid 流程图 → 改用
```mermaid代码块 - 不要用代码块包裹单行公式 → 改用
$行内公式$
9. 引用块与列表
9.1 引用块的正确用途
引用块 > 仅用于以下场景：
- 文章开头的"目标"和"前置要求"提示
- 引用他人的话或文献原文
- 引用重要警告或注意事项
> **目标**：掌握深度学习核心概念。
>
> **前置要求**：Python 基础。
9.2 不要用引用块的情况
概念解释、步骤叙述、类比说明等正文内容不应该使用引用块：
**错误**：
> 张量和数组在数据结构上是一样的，但张量有两个关键特性：
> 1. 可以在 GPU 上运算
> 2. 支持自动求导
**正确**：
张量和数组在数据结构上是一样的，但张量有两个关键特性：
1. 可以在 GPU 上运算
2. 支持自动求导
9.3 列表使用
- 有序列表用于步骤说明
- 无序列表用于并列观点
- 不要用列表冒充标题：禁止
1. #### 标题这类写法
10. 表格使用规范
10.1 适用场景
- 对比不同模型、方法、激活函数的特性
- 列出参数、超参数
- 展示实验结果
10.2 格式
| 列1 | 列2 | 列3 |
| --- | --- | --- |
| 数据 | 数据 | 数据 |
10.3 不要用表格的情况
- 不要用表格做 ASCII 图形展示 → 用 Mermaid 或代码块
- 不要把长段文字塞进表格单元格 → 用正文 + 列表
11. 图片与资源
11.1 存放与命名
- 图片存放路径：
static/img/<文章名>/，例如static/img/loss-functions/ - 命名规范：使用小写英文 + 连字符（kebab-case），例如
kl-divergence.svg、focal_loss.svg - 格式选择：
- SVG：首选格式。矢量图，任意缩放不失真，文件小，适合函数图像、流程图、概念示意图
- PNG或JPG：需要截图、照片或复杂渲染时使用
- 避免使用 GIF（文件大）或 BMP（无压缩）
11.2 引用方式
- 使用 Markdown 语法，并必须填写 alt 文本（用于 SEO 和无障碍访问）：
- 路径以
/img/开头（对应static/img/），Hugo 构建时会正确解析 - alt 文本应简洁描述图像内容，不要写"图片"或"figure"
11.3 预生成图片（matplotlib 等）
对于函数图像、数据可视化等需要精确数学描述的内容，推荐使用 matplotlib 预生成 SVG 后嵌入文章：
- 编写 Python 脚本生成图像，保存到
static/img/<文章名>/ - 在 Markdown 中用
引用 - Hugo 构建时会自动将
static/img/中的文件复制到public/img/
不需要修改 Hugo 配置或引入额外 JavaScript 依赖。
12. 文章结构模板
## 1. 模块标题
### 1.1 概念名称
#### 子概念
**类比：形象比喻**
正文解释...
$$
公式
$$
```
代码/推导
```
**要点总结**：
| 对比项 | A | B |
| --- | --- | --- |
13. 常见错误排查清单
13.1 渲染问题清单
在发布前，检查以下问题：
- 所有
$行内公式两边无多余空格 -
$$块内无#注释符 -
$$块内无纯中文长句（用\text{}包裹或移到公式外） -
$$块内<后紧跟字母时已转义为\lt（如x_{\lt t}，防止 Hugo 误认为 HTML 标签） - Mermaid 节点标签中的全角字符（
（）：）已用双引号包裹 - Mermaid 中无 emoji
- 正文内容未错误使用引用块
> - 无残留的 ASCII 表格（已转为 Markdown 表格）
- 无残留的 ASCII 流程图（已转为 Mermaid）
13.2 格式问题清单
- 标题未加粗重复：
### 1. **核心概念**→### 1. 核心概念 - 无列表套标题：
1. #### 步骤一→#### 1. 步骤一 - 标题层级未跳跃：
##下面不直接出现#### - 无伪标题：
**关键概念**→### 关键概念 - 块级元素（标题、代码块、分割线）前后有空行
- 中英文混排之间有半角空格
- 中文标点使用全角
- 正文从
##开始，未使用# - Hugo 构建无报错：
hugo命令 0 错误 - 浏览器预览确认公式和图表正常渲染
14. 跨文章导航与 relref 链接规范
14.1 relref 格式
Hugo 的 relref shortcode 用于生成站内文章的正确链接。在内容文件中使用标准 shortcode 语法：
{{< relref "文章文件名" >}}
书写时注意：上方代码块中
/*和*/是 Hugo 的转义标记，仅用于在页面上展示 shortcode 原文。你自己写文章时去掉这对标记，直接写{{< relref "你的文件名" >}}去掉/**/即可。
示例：
[速通 AI（二）：深度学习与 PyTorch](/posts/tech/%E9%80%9F%E9%80%9Aai-02-%E6%B7%B1%E5%BA%A6%E5%AD%A6%E4%B9%A0%E4%B8%8Epytorch/)
14.2 不要用普通路径链接
禁止使用普通 Markdown 链接指向站内文章：
[下一篇](/posts/tech/深度学习与PyTorch) ← 错误！不会生成正确的相对路径
正确使用 relref：
[速通 AI（二）：深度学习与 PyTorch](/posts/tech/%E9%80%9F%E9%80%9Aai-02-%E6%B7%B1%E5%BA%A6%E5%AD%A6%E4%B9%A0%E4%B8%8Epytorch/) ← 正确
14.3 系列文章导航格式
系列文章（如「速通 AI」系列）应在文章开头和结尾添加导航链接：
开头（上一篇）：
**上一篇**：[速通 AI（一）：编程与人工智能数学基础](/posts/tech/%E9%80%9F%E9%80%9Aai-01-%E7%BC%96%E7%A8%8B%E4%B8%8E%E4%BA%BA%E5%B7%A5%E6%99%BA%E8%83%BD%E6%95%B0%E5%AD%A6%E5%9F%BA%E7%A1%80/) — Python 基础、微积分、线性代数、概率统计、机器学习入门。
结尾（下一篇预告）：
---
> **下一篇预告**：本文建立了 Python 编程和数学基础。在[速通 AI（二）：深度学习与 PyTorch](/posts/tech/%E9%80%9F%E9%80%9Aai-02-%E6%B7%B1%E5%BA%A6%E5%AD%A6%E4%B9%A0%E4%B8%8Epytorch/)中，你将看到今天学的矩阵乘法如何在 GPU 上通过 PyTorch 加速。
14.4 relref 引用的文件名规则
- 不要加
.md后缀：/posts/tech/%E9%80%9F%E9%80%9Aai-02-%E6%B7%B1%E5%BA%A6%E5%AD%A6%E4%B9%A0%E4%B8%8Epytorch/（正确） - 不要加路径：
/posts/tech/%E9%80%9F%E9%80%9Aai-02-%E6%B7%B1%E5%BA%A6%E5%AD%A6%E4%B9%A0%E4%B8%8Epytorch/（正确），不要写content/posts/tech/速通AI-02-深度学习与PyTorch - 不要加特殊字符：文件名与 relref 中的引用必须完全一致
15. 快速对照表
| 内容类型 | 格式 | 示例 |
|---|---|---|
| 数学公式（行内） | $...$ | $y = wx + b$ |
| 数学公式（独立） | $$...$$ | $$\frac{\partial L}{\partial x}$$ |
| 流程图/依赖图 | ```mermaid | flowchart TD |
| Python 代码 | ```python | import torch |
| Shell 命令 | ```bash | pip install ... |
| 数学推导 | ```（无标记） | ∂L/∂z = z - y |
| 概念类比 | 正文 + 加粗 | **类比**：XXX |
| 对比数据 | Markdown 表格 | | A | B | |
| 文章开头提示 | > 引用块 | > **目标**：XXX |
| 公式内中文注释 | \text{} | \quad \text{（说明）} |
| 代码/文件名 | 行内代码 | `config.yml` |
| 图片（PNG） | Markdown 图片 |  |
| 图片（SVG，首选） | Markdown 图片 |  |
| 站内文章链接 | relref shortcode | {{< relref "文件名" >}} ¹ |
| 系列导航（上一篇） | **上一篇**：[标题](relref) | 见 §14.3 |
| 系列导航（下一篇） | > **下一篇预告**：... | 见 §14.3 |
¹ 表中 {{< >}} 为转义语法，仅用于展示。你写文章时去掉 /* */ 即可。