Markdown 完全使用指南：从语法规范到工程化写作#

适用：所有用 Markdown 写笔记、博客、README、技术文档的人。 阅读门槛：零。看完你能独立写出排版规范的技术文档，并能排查 90% 的”为什么没渲染出来”问题。

一、Markdown 是什么#

Markdown 是 John Gruber 在 2004 年发布的轻量级标记语言，核心思想只有一句话：

用最简单的纯文本符号表达文档结构，让人在”不渲染的源码状态下”也能顺畅阅读，同时可以一键转换成 HTML。

它解决的问题：

0.1 常见”方言”#

Markdown 早年没有统一标准，于是出现了多个超集（扩展集）。记住这张关系图：

flowchart TB
    MD["Markdown 原始语法<br/>Gruber 2004"]
    CM["CommonMark<br/>2014 起的标准化规范"]
    GFM["GFM（GitHub Flavored）<br/>表格 / 任务列表 / 删除线 / 自动链接"]
    MDX["MDX<br/>Markdown 内嵌 JSX 组件"]
    PM["Pandoc / MultiMarkdown<br/>脚注 / 定义列表 / 数学公式 / 引用文献"]
    MD --> CM
    CM --> GFM
    CM --> MDX
    CM --> PM
    GFM --> SITE["本博客：Astro<br/>GFM + Mermaid + Frontmatter + MDX"]
    PM -.部分语法.-> SITE

• CommonMark：事实标准，明确了原始 Markdown 中大量歧义（比如缩进到底几个空格、嵌套引用怎么解析）。
• GFM：GitHub 推出的超集，是目前事实上支持度最广的扩展。表格、任务列表、删除线都来自它。
• MDX：在 Markdown 里直接写 JSX 组件，本站已启用（.mdx 文件）。
• Pandoc / MultiMarkdown：面向学术出版，多了脚注、定义列表、公式等。

⚠️ 关键认知：“Markdown 能不能渲染某个语法”取决于渲染器，而不是语法本身。同一个 ==高亮==，Obsidian 能渲染，GitHub 就不行。写文档前先确认目标平台支持什么。

0.1b 本文的演示约定#

每个语法都给两段内容：

• 写什么：放在 ```markdown 代码块里的源码；
• 看到什么：紧跟其后的真实渲染效果。

二、最小可用文档与渲染管线#

一份麻雀虽小五脏俱全的 Markdown：

# 文档标题

这是一个段落，里面可以有 **加粗**、*斜体*、`行内代码` 和[链接](https://example.com)。

## 二级标题

- 列表项一
- 列表项二

1. 有序列表
2. 第二项

> 这是一段引用。

```python
print("代码块，支持语法高亮")
```

| 表头 A | 表头 B |
|---|---|
| 单元格 | 单元格 |

从你敲下字符到浏览器看到页面，中间发生了什么：

flowchart LR
    A["① Markdown 源文件<br/>.md 纯文本"] --> B["② 解析器<br/>remark / marked / markdown-it"]
    B --> C["③ 语法树 AST<br/>mdast（节点对象）"]
    C --> D["④ 插件处理<br/>表格/锚点/代码高亮…"]
    D --> E["⑤ 转换为 HTML AST<br/>hast"]
    E --> F["⑥ 输出 HTML<br/>浏览器渲染成页面"]
    G["Frontmatter<br/>YAML 元数据"] -.-> C

理解这条管线的意义：出问题时能分层定位——源码对不对？解析器认不认这个语法？插件有没有处理？CSS 有没有把样式藏掉？后面排障章节都按这个思路走。

三、基础语法全解#

2.1 标题#

写什么（ATX 风格，# 号，最常用）：

# 一级标题
## 二级标题
### 三级标题
#### 四级标题
##### 五级标题
###### 六级标题

规范要点：

1. # 后必须有一个空格，#标题 在严格解析器里不生效。
2. 不要跳级：# 之后直接 ### 会让文档大纲断裂，自动生成的目录会缺层。
3. 一篇文档建议只有一个一级标题（本站文章正文顶部的 # 即此用途）。
4. 另一种 Setext 风格（=== 和 --- 下划线）能用但不推荐：

一级标题
=======

二级标题
-------

本站会为每个标题自动生成锚点 id，鼠标悬停标题会出现 #，例如本文的”二、基础语法全解”可直接通过 #二基础语法全解 深链分享。

2.2 段落与换行#

这是新手第一大坑。Markdown 的换行规则：

• 单个回车 = 同一段落内的空格（软换行），不会产生新行；
• 空一行 = 新段落（<p> 标签，段间距大）；
• 行尾两个空格再回车 = 硬换行（<br>），或者行尾加一个反斜杠 \。

写什么：

第一行（行尾没有空格）
第二行，会和上面连成同一段。

第一段结束。

第二段开始，中间隔了一个空行。

硬换行第一行··
硬换行第二行（上一行行尾有两个空格，用 · 表示）

看到什么：

第一行（行尾没有空格） 第二行，会和上面连成同一段。

第一段结束。

第二段开始，中间隔了一个空行。

硬换行第一行
硬换行第二行（上一行行尾有两个空格）

💡 两个尾随空格在编辑器里看不见，极易丢失。更推荐行尾反斜杠或干脆用空行分段。本站代码块以外的中文写作，建议一律用”空行分段”，最稳。

2.3 文字样式#

写什么：

*斜体* 或 _斜体_
**加粗** 或 __加粗__
***粗斜体***
~~删除线~~（GFM）
`行内代码`
***粗斜体还能嵌套**在斜体里***

看到什么：

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

规则细节：

• * 和 _ 的区别：词内强调用 * 更稳。比如 snake_case_name 里的下划线不能被当成斜体符号，CommonMark 规定 _ 在词内不生效，而 * 按配对解析——但不同方言实现不同，技术文档统一用 *。
• ==高亮==、上标^2^、下标 H~2~O 不是通用语法，GFM/GitHub 不支持，需要插件（如 Obsidian、remark-directive）。本站当前未启用，写了会原样显示等号。
• 加粗和行内代码可以嵌套：**包含code` 的加粗**” 中反引号优先级最高，按字面处理星号。

2.4 列表#

无序列表#

-、*、+ 三种符号等价，全文统一用 -：

- 第一项
- 第二项
- 第三项

• 第一项
• 第二项
• 第三项

有序列表#

1. 第一步
2. 第二步
3. 第三步

1. 第一步
2. 第二步
3. 第三步

💡 有序列表的编号源码里写几都无所谓，渲染器会自动重排。为了 diff 友好（插入一项不用改后面所有编号），有人喜欢全写 1.：

1. 第一项
1. 第二项
1. 第三项

嵌套：缩进的坑#

子项缩进必须与父项文字对齐。用 -（符号+空格，共 2 列）时，子项缩进 2 个空格：

- 父项
  - 子项（2 空格）
    - 孙项（4 空格）
1. 有序父项
   1. 有序子项（"1. " 是 3 列，所以缩进 3 空格）

• 父项
  • 子项（2 空格）
    • 孙项（4 空格）

1. 有序父项
   1. 有序子项（缩进 3 空格）

⚠️ 经典坑：4 空格缩进会被当成代码块。CommonMark 规定行首 4 个空格是缩进代码块，所以无序列表项下直接空 4 格写内容，常常意外变成代码。用 2 空格嵌套 + 用围栏代码块（三反引号）替代缩进代码块，可避开 90% 的列表问题。

列表项内放多个段落/代码块时，后续内容要缩进到与文字对齐：

- 第一项

  第一项的第二段（缩进 2 空格，与"第"字对齐）

- 第二项

任务列表（GFM）#

- [x] 已完成
- [x] 另一个已完成
- [ ] 未完成
- [ ] 方括号里必须是小写 x 或空格

• 已完成
• 另一个已完成
• 未完成
• 方括号里必须是小写 x 或空格

2.5 链接#

写什么（四种形式）：

① 行内链接：[显示文字](https://example.com "可选的 title，悬停显示")
② 引用式链接：[显示文字][ref1]
③ 引用简写：[Example][]
④ 裸链接自动识别（GFM）：直接写 https://example.com

[ref1]: https://example.com "引用定义可以放在文档任意位置"
[Example]: https://example.com

看到什么：

① 显示文字 ② 显示文字 ③ Example ④ https://example.com

实战建议：

• 同一个链接出现多次 → 用引用式，正文干净、改 URL 只改一处。
• 页内锚点：[跳到标题](#二级标题)。中文锚点的生成规则各平台不同（GitHub 会保留中文、去掉标点空格小写化），本站由 rehype-slug 自动生成，直接用浏览器复制标题链接最保险。
• 本站正文里的外部链接会自动加上 target="_blank"，新窗口打开，不用自己处理。
• 邮箱用 <robin@example.com> 会渲染成可点击的 mailto 链接；但邮箱仍以明文出现在 HTML 源码中，无法防爬虫，防爬需 JS 混淆或实体编码：robin@example.com。

2.6 图片#

语法是链接前面加一个 !：

![图片加载失败时显示的替代文字](图片地址 "可选 title")

![引用式图片][logo]

[logo]: /images/logo.svg "Logo"

要点：

• alt 文本必填：图片挂了时显示，也是无障碍读屏器朗读的内容，SEO 也用它。
• 路径：Markdown 文件里用相对路径或站点绝对路径（本站图片放 public/ 下，引用时写 /images/xxx.png）。
• 控制图片尺寸/居中：标准 Markdown 做不到，直接内嵌 HTML：

<img src="/images/demo.png" alt="示例" width="480" style="display:block;margin:0 auto" />

• 图片本身做链接：[![alt](img.jpg)](https://example.com)。

2.7 引用块#

行首 > + 空格：

> 一级引用
>
> > 二级嵌套引用（中间也要有空的 > 行）
>
> 回到一级，引用里可以放 **加粗**、`代码`、列表：
>
> - 项一
> - 项二

一级引用

二级嵌套引用

回到一级，引用里可以放 加粗、代码、列表：

• 项一
• 项二

2.8 分隔线#

三个或更多 *、-、_，可以含空格：

***
---
- - -

效果都是一条横线（本文未再插入，避免割裂章节）。注意 --- 前面必须有空行，否则可能被解析成 Setext 标题下划线，或被当成 YAML frontmatter 的结束符（见排障章）。

2.9 代码#

行内代码：单反引号#

执行 `npm run build` 命令，注意 `PATH` 环境变量。

执行 npm run build 命令，注意 PATH 环境变量。

行内代码里的所有符号都按字面文本处理（只有配对的反引号有分隔代码跨度的含义），这就是为什么本文能用行内代码安全展示 **、#、\ 等符号。

代码块：三个反引号（围栏式，推荐）#

```bash
echo "hello"
ls -lh /etc/nginx
```

echo "hello"
ls -lh /etc/nginx

要点：

1. 开头围栏后写语言标识（bash/python/json/yaml/sql…），本站用 Shiki 按语言上色。
2. 纯文本也要写：不想高亮就写 text 或 plaintext，别留空——留空在某些主题下样式会不一致。
3. 代码块内要出现三个反引号怎么办？ 外层用四个反引号：

````markdown
```python
print("像这样演示 Markdown 代码块语法本身")
```
````

4. 老式缩进代码块（行首 4 空格）能不用就不用——和列表嵌套规则冲突，且不能指定语言。

本站另对纯 ASCII 字符画做了等宽字体对齐处理（示意图自动用更纱黑体等宽字体），普通代码块不受影响。

2.10 表格（GFM）#

| 左对齐 | 居中对齐 | 右对齐 |
|:-------|:--------:|-------:|
| 单元格 |  单元格  | 单元格 |
| 长内容会自动换行，竖线 `|` 要转义成 `\|` | 第二列 | 123 |

规则：

1. 第二行的 --- 定义列，冒号控制对齐：:--- 左、:---: 中、---: 右；不写冒号默认左对齐。
2. 两侧竖线可省略，但建议保留，源码可读性好。
3. 单元格内 | 必须写成 \|；单元格内可以用行内代码、加粗、链接，但不能用多级列表、标题、代码块——表格只支持行内内容。
4. 表格前后必须各留一个空行，否则可能不渲染。

2.11 转义字符#

当你就是想显示星号、井号等符号本身时，前面加反斜杠 \：

\# 不是标题
\* 不会斜体 \*
\- 不会变成列表
\| 不是表格竖线

# 不是标题
* 不会斜体 *
- 不会变成列表
| 不是表格竖线

可转义的 ASCII 标点（CommonMark 基础集；GFM 额外扩展了 | 和 ~，本站已启用）：

\  `  *  _  { }  [ ]  ( )  #  +  -  .  !  |  ~

💡 反斜杠只转义标点符号，转义字母无效（\n 就是字面的反斜杠+n，不会换行）。中文标点（，。、等）本来就不是 Markdown 符号，不需要也不应该加反斜杠。

2.12 内嵌 HTML#

Markdown 原生支持直接写 HTML，渲染时原样保留：

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

Markdown 内容可以直接写在 HTML 块内（注意块标签与正文间留空行）。

</details>

常用场景：折叠块 <details>、图片尺寸、上下标 <sub>/<sup>、跳转锚点。⚠️ 注意 GitHub 的 issue/评论等场景会过滤部分 HTML 标签；企业文档平台出于安全（XSS）也常做白名单过滤，发布前实测。

四、GFM 四大扩展速览#

GFM 在 CommonMark 基础上加了四样东西，本站全部支持：

五、进阶语法（按渲染器支持，使用前确认）#

4.1 脚注#

Pandoc / GitHub 文档 / 多数笔记软件支持，语法是 [^标识]：

这是一个有脚注的句子[^1]，也可以用命名脚注[^note]。

[^1]: 脚注内容，会被收集到文末。
[^note]: 命名脚注，比纯数字好维护。

⚠️ 本站当前未启用脚注插件，在本站文章里写 [^1] 会原样显示。需要时应改用”行内括号补充”或文末”参考资料”列表。GitHub 渲染 README 时则支持。

4.2 数学公式#

基于 LaTeX 语法，需要 KaTeX / MathJax 插件（如 remark-math + rehype-katex）：

行内公式：质能方程 $E = mc^2$

块级公式：
$$
\frac{\partial \rho}{\partial t} + \nabla \cdot (\rho \mathbf{v}) = 0
$$

本站未启用公式插件。技术博客要写公式时的变通：用 Unicode 符号（E = mc²、≤、∞、Σ）或贴图。

4.3 Mermaid 图表（本站支持 ✅）#

本站集成了 astro-mermaid，直接用 mermaid 代码块即可，构建时不依赖浏览器、明暗主题自动切换：

```mermaid
sequenceDiagram
    participant U as 用户浏览器
    participant A as Vercel 函数
    participant D as DeepSeek
    U->>A: 发送问题
    A->>D: 转发（带 API Key）
    D-->>A: 返回回答
    A-->>U: 流式输出
```

sequenceDiagram
    participant U as 用户浏览器
    participant A as Vercel 函数
    participant D as DeepSeek
    U->>A: 发送问题
    A->>D: 转发（带 API Key）
    D-->>A: 返回回答
    A-->>U: 流式输出

支持流程图 flowchart、时序图 sequenceDiagram、状态图 stateDiagram-v2、甘特图 gantt、类图等。注意：节点 ID 用英文、中文放 ["…"] 里、不合法的 DSL 会导致该图渲染失败（本站有语法校验脚本，发布前必跑）。

4.4 Frontmatter（YAML 元数据）#

以 --- 包裹的 YAML 块，必须放在文件最开头：

---
draft: false
title: "文章标题"
snippet: "一句话摘要"
publishDate: "2026-09-10"
category: "工具"
tags: ["Markdown", "写作"]
---

本站用 Content Collection 的 schema 严格校验这些字段。这是本站最容易翻车的地方，三条铁律：

1. publishDate 必须加引号，否则 YAML 解析成日期对象而非字符串；
2. 双引号包裹的值内部不要再出现中文双引号，改用书名号《》；
3. 分隔符只能是三个短横线 ---。曾有桌面编辑器把它”优化”成 MultiMarkdown 风格的 ***，导致构建直接失败（详见排障章第 9 条）。

4.5 其他常见扩展#

六、本站 Markdown 支持矩阵#

给在这个博客上写文章的人一张确定的表：

七、工具链#

6.1 编辑器怎么选#

markdownlint 规则建议（最值得开的几条）：

• MD009 行尾不许有多余空格（顺手消灭不可见的硬换行歧义）；
• MD012/MD022 标题前后必须空行；
• MD025 单文件只许一个一级标题；
• MD040 代码块必须指定语言。

6.2 Pandoc：格式转换瑞士军刀#

# Markdown → HTML（独立文件，带样式）
pandoc input.md -o output.html --standalone

# Markdown → Word（给非技术同事）
pandoc input.md -o output.docx

# Markdown → PDF（需额外装 LaTeX，或走 HTML 打印）
pandoc input.md -o output.pdf --pdf-engine=xelatex -V CJKmainfont="PingFang SC"

# Word → Markdown（反向迁移资料）
pandoc input.docx -o output.md --wrap=none

6.3 git 版本管理#

Markdown 纯文本天生适合 git：每次改动、每个字都可追溯。两条实践：

1. 一句话一段（或一个要点一段）：git diff 按行对比，段落写成一整坨会让”改了两个字”显示成整段重写；中文写作每句一个换行（渲染时空行分段、单换行不影响版面）是兼顾源码 diff 和渲染的好习惯——本文即按此风格书写。
2. 提交信息写人话：fix: 修正 chrony 离线恢复时间描述 远胜于 update。

八、语法速查表（打印贴墙版）#

九、高频坑与排障（按出现频率排序）#

1. 换行没生效，全挤成一段#

原因：单回车在 Markdown 里是空格。修复：段落间空一行；需要同段换行用行尾两空格或 \。

2. 列表后面写什么都”陷进”列表里#

原因：列表后的内容没有空行，或缩进还停留在列表层级。修复：列表结束后空一行且顶格写；列表内多段落要正确缩进对齐。

3. 表格不渲染，原样显示竖线#

排查三连：①第二行是不是 |---|---| 结构；②表格前后有没有空行；③单元格内的竖线是否转义成 \|。

4. 代码块里的三个反引号把块提前闭合了#

修复：外层围栏用四个反引号 ````；嵌套几层就比内层多一个反引号。

5. 星号/下划线显示异常（snake_case 变斜体）#

修复：技术标识符一律用行内代码包裹（client_id），或用 \_ 转义；强调统一用 * 不用 _。

6. 图片裂图#

排查：①路径大小写（Linux/部署环境区分大小写，本地 macOS 可能不区分）；②相对路径基准；③public/ 资源引用应写站点绝对路径；④alt 正常但 404 → 直接 curl 图片 URL 看状态码。

7. 标题没有锚点 / 目录缺层#

不要跳级（## 后直接 ####）；锚点 id 由插件生成，中文标点会被剔除，直接从浏览器复制目标标题链接最可靠。

8. 内嵌 HTML 被平台吞掉#

目标平台做了 XSS 白名单过滤。GitHub Markdown 允许部分标签（details、sup、img 等），但企业 IM/文档站策略各不相同——以目标平台实测为准，别信本地预览。

9. ★ Frontmatter 被编辑器改写成 *** 导致构建失败（本站真实事故）#

现象：某篇文章开头变成下面这样，Astro 提示找不到 frontmatter、整站构建失败：

***
draft: false
tags:
- Markdown
***
正文……

根因：某些桌面 AI 编辑器（如 WorkBuddy 的文档引擎）在监控/打开项目文件夹时，会把标准 YAML 头（--- 分隔）按 MultiMarkdown 规范”格式化回写”成 *** 包裹的变体。

本站的防护（已自动化，无需手动处理）：

• npm run build / npm run dev 启动前会自动运行 frontmatter 守卫脚本，把 *** 变体洗回标准 --- YAML；
• 手动修复命令：npm run fix:frontmatter；
• 预防：不要让这类编辑器监控本项目目录；判断是否被污染只需看文件第一行是不是 ---。

10. 中文标点被乱加反斜杠#

有些编辑器导出时会把 _、[、] 前加 \（Markdown 转义），连 YAML 值里的都不放过（如 sshd\_config、tags: \["x"\]）。在正文里多数能容错显示，但进了 frontmatter 就会污染数据。同样由上面的守卫脚本清洗；根因仍是不要用会回写文件的编辑器打开项目。

11. Mermaid 图显示成代码/白底错误图#

排查：①语言标识必须是小写 mermaid；②DSL 语法错误（连线符号、未定义节点）；③发布前用本站脚本校验：

node scripts/_mmd-check-article.mjs 你的文章文件名.md

12. 迁移到新平台后排版变了#

根因：方言差异。迁移前用 Pandoc 做一轮转换检查，并重点核对：脚注、公式、任务列表、HTML 标签、==高亮==、定义列表这六个”方言重灾区”。

十、写作自检清单#

发布前过一遍：

• 全文只有一个 # 一级标题，标题层级不跳级，标题前后有空行
• 段落之间有空行；没有依赖”看不见的尾随空格”做换行
• 列表符号统一 -；嵌套缩进正确（无序 2 空格、有序 3 空格）
• 所有代码块指定了语言；演示代码块语法时外层用了 4 个反引号
• 表格前后有空行、对齐冒号正确、单元格竖线已转义
• 链接有意义文字（不是”点这里”）；图片有 alt 文本
• 需要显示的符号已用行内代码或反斜杠处理
• 目标平台不支持的扩展（脚注/公式/高亮/提示块）已替换为兼容写法
• frontmatter 是标准 --- 包裹、日期加引号、值内无中文双引号嵌套
• 含 Mermaid 图时跑过校验脚本；本地 npm run build 零错误

附录：学习与规范参考#

• CommonMark 官方规范与交互试验：https://commonmark.org/
• GFM 规范：https://github.github.com/gfm/
• Pandoc 手册（最全的方言实现参考）：https://pandoc.org/MANUAL.html
• Mermaid 文档：https://mermaid.js.org/
• markdownlint 规则列表：https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md

一句话收尾：Markdown 的”简单”是表象，它真正的价值是让内容与排版工具解耦——同一份纯文本，GitHub 能渲染、博客能构建、Pandoc 能出 PDF、十年后任何编辑器都能打开。把语法学扎实、把方言边界搞清楚，你的文字资产才真正属于自己。