技术文章格式规约

本文档定义了博客中技术文章（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**)：用于强调关键概念或重点结论，不要滥用
行内代码 (`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 禁止事项

错误写法	问题	正确写法
`$$ 中文文字 $$`	非 LaTeX 内容放在 `$$` 内	用 `$公式$` 或普通文本
`$$ x # 注释 $$`	`#` 被解析为颜色	用 `\text{注释}`
$x $	`$` 旁有空格	$x$

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. 图片与资源

图片存放：建议文章相关的图片存放在 static/img 目录下，按分类或文章名归档
图片引用：使用 Markdown 语法，并填写 alt 文本以便 SEO
- ![图片描述](/img/path/to/image.png)

12. 文章结构模板

## 1. 模块标题

### 1.1 概念名称

#### 子概念

**类比：形象比喻**

正文解释...

$$
公式
$$

```　
代码/推导
```　

**要点总结**：

| 对比项 | A | B |
| --- | --- | --- |

13. 常见错误排查清单

13.1 渲染问题清单

在发布前，检查以下问题：

所有 $ 行内公式两边无多余空格
$$ 块内无 # 注释符
$$ 块内无纯中文长句（用 \text{} 包裹或移到公式外）
Mermaid 节点标签中的全角字符（（）：）已用双引号包裹
Mermaid 中无 emoji
正文内容未错误使用引用块 >
无残留的 ASCII 表格（已转为 Markdown 表格）
无残留的 ASCII 流程图（已转为 Mermaid）

13.2 格式问题清单

标题未加粗重复：### 1. **核心概念** → ### 1. 核心概念
无列表套标题：1. #### 步骤一 → #### 1. 步骤一
标题层级未跳跃：## 下面不直接出现 ####
无伪标题：**关键概念** → ### 关键概念
块级元素（标题、代码块、分割线）前后有空行
中英文混排之间有半角空格
中文标点使用全角
正文从 ## 开始，未使用 #
Hugo 构建无报错：hugo 命令 0 错误
浏览器预览确认公式和图表正常渲染

14. 快速对照表

内容类型	格式	示例
数学公式（行内）	$...$	$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`
图片	Markdown 图片	`![描述](/img/xxx.png)`

错误写法	问题	正确写法
`$$ 中文文字 $$`	非 LaTeX 内容放在 `$$` 内	用 `\(公式\)` 或普通文本
`$$ x # 注释 $$`	`#` 被解析为颜色	用 `\text{注释}`
$x $	`$` 旁有空格	$x$

1. Front Matter 规范#

2. 结构与标题#

2.1 标题层级#

2.2 标题编号风格#

2.3 标题样式#

2.4 禁止伪标题#

3. 段落与间距#

3.1 段落空行#

3.2 段落首行缩进#

3.3 块级元素间距#

4. 全角与半角#

5. 强调与行内语法#

6. 数学公式（KaTeX）#

6.1 行内公式#

6.2 独立公式块#

6.3 公式与中文注释的正确搭配方式#

6.4 禁止事项#

7. Mermaid 图表#

7.1 基本语法#

7.2 节点标签引号规则#

7.3 Edge 标签引号规则#

7.4 禁止事项#

8. 代码块规范#

8.1 代码块用途分类#

8.2 代码块必须指定语言标识符#

8.3 什么时候用代码块 vs 正文#

8.4 不要用代码块的情况#

9. 引用块与列表#

9.1 引用块的正确用途#

9.2 不要用引用块的情况#

9.3 列表使用#

10. 表格使用规范#

10.1 适用场景#

10.2 格式#

10.3 不要用表格的情况#

11. 图片与资源#

12. 文章结构模板#

13. 常见错误排查清单#

13.1 渲染问题清单#

13.2 格式问题清单#

14. 快速对照表#