# markdown标准和扩展语法及查看器特性搜集


> 本文档本身就是一个 **Markdown 语法演示文件**，每一节都同时展示「源码写法」和「渲染效果」。
> 目标：覆盖 CommonMark 核心 + GFM 扩展 + Pandoc 等方言常用特性。

---

## 目录

- [一、标题](#一标题)
- [二、段落与换行](#二段落与换行)
- [三、文本格式化（行内）](#三文本格式化行内)
- [四、引用块](#四引用块)
- [五、列表](#五列表)
- [六、代码](#六代码)
- [七、水平线](#七水平线)
- [八、链接](#八链接)
- [九、图片](#九图片)
- [十、转义与实体](#十转义与实体)
- [十一、HTML 混排](#十一html-混排)
- [十二、GFM 扩展语法](#十二gfm-扩展语法)
- [十三、Pandoc / 学术扩展](#十三pandoc--学术扩展)
- [十四、方言兼容速查表](#十四方言兼容速查表)

---

## 一、标题

Markdown 支持两种标题风格：**ATX**（井号）和 **Setext**（下划线）。

### ATX 风格（推荐）

源码：

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

渲染效果见本文档各级标题。

### Setext 风格（仅一级、二级）

源码：

```markdown
一级标题
========

二级标题
--------
```

> **注意**：Setext 下划线至少 2 个字符，等号 = 一级，减号 - 二级。

---

## 二、段落与换行

段落由**空行**分隔。这是第一个段落。

这是第二个段落，和上一个段落之间有一个空行。

**硬换行**（行尾两空格 + 回车）：  
这一行末尾有两个空格，所以会强制换行。

**软换行**（直接回车）则只是源码换行，渲染后仍是同一段。

---

## 三、文本格式化（行内）

| 效果 | 写法 | 说明 |
|---|---|---|
| *斜体* | `*斜体*` 或 `_斜体_` | 单星号 / 单下划线 |
| **粗体** | `**粗体**` 或 `__粗体__` | 双星号 / 双下划线 |
| ***粗斜体*** | `***粗斜体***` | 三星号 |
| ~~删除线~~ | `~~删除线~~` | GFM 扩展 |
| `行内代码` | `` `行内代码` `` | 反引号 |
| 上标 x² | `x^2^` | Pandoc 扩展 |
| 下标 H₂O | `H~2~O` | Pandoc 扩展 |
| [链接](#) | `[链接](#)` | 行内链接 |

混合示例：

> 这是一段**粗体**和*斜体*以及***粗斜体***的组合，还有`code`和~~删除~~效果。

---

## 四、引用块

源码：

```markdown
> 这是一级引用。
>
> 可以有多段，段落间用空行 + 大于号分隔。
>
> > 这是嵌套引用（二级）。
> >
> > #### 引用里还能放标题
> >
> > - 以及列表
> > - 甚至代码块
```

渲染效果：

> 这是一级引用。
>
> 可以有多段，段落间用空行 + 大于号分隔。
>
> > 这是嵌套引用（二级）。
> >
> > #### 引用里还能放标题
> >
> > - 以及列表
> > - 甚至代码块

---

## 五、列表

### 无序列表

源码：

```markdown
- 苹果
- 香蕉
  - 嵌套：芭蕉
  - 嵌套：小米蕉
- 橙子
```

渲染效果：

- 苹果
- 香蕉
  - 嵌套：芭蕉
  - 嵌套：小米蕉
- 橙子

> 三种符号 `-` `*` `+` 都合法，但**同一列表请保持一致**。

### 有序列表

源码：

```markdown
1. 第一步
2. 第二步
   1. 子步骤 A
   2. 子步骤 B
3. 第三步
```

渲染效果：

1. 第一步
2. 第二步
   1. 子步骤 A
   2. 子步骤 B
3. 第三步

> **序号值不影响渲染**：写成 `1.` `1.` `1.` 也会输出 1、2、3。但建议写正确序号方便回退到纯文本阅读。

### 任务列表（GFM）

源码：

```markdown
- [ ] 未完成的任务
- [x] 已完成的任务
- [ ] 另一个待办
  - [x] 子任务已完成
```

渲染效果（在支持 GFM 的平台）：

- [ ] 未完成的任务
- [x] 已完成的任务
- [ ] 另一个待办
  - [x] 子任务已完成

### 定义列表（Pandoc / MultiMarkdown）

源码（Pandoc 风格）：

```markdown
术语 A
  ~ 这是术语 A 的定义，可以有多段。

术语 B
  ~ 第一定义。
  ~ 第二定义（同义词）。
```

> 定义列表在 CommonMark / GFM 中**不原生支持**，需要 Pandoc 等扩展。

---

## 六、代码

### 行内代码

用反引号包裹：`` `const x: number = 42;` `` 渲染为 `const x: number = 42;`。

当代码本身含反引号时，用**双反引号**：```` `` `backtick` inside `` ```` 渲染为 `` `backtick` inside ``。

### 围栏代码块（推荐）

源码：

````markdown
```javascript
function greet(name) {
  console.log(`Hello, ${name}!`);
}
greet("World");
```
````

渲染效果：

```javascript
function greet(name) {
  console.log(`Hello, ${name}!`);
}
greet("World");
```

### 缩进代码块（原始风格）

源码（每行缩进 4 空格）：

```markdown
    # 这是缩进代码块
    def hello():
        print("hi")
```

渲染效果：

    # 这是缩进代码块
    def hello():
        print("hi")

> 缩进式代码块在 CommonMark 中仍支持，但**围栏式更直观、可指定语言**。

---

## 七、水平线

三种写法（至少 3 个字符，可含空格）：

源码：

```markdown
---

***

___
```

渲染效果：

---

---

---

---

---

---

---

> 注意：横线上下**必须有空行**，否则可能被解析为标题下划线（Setext）。

---

## 八、链接

### 行内链接

源码：

```markdown
[OpenAI](https://openai.com)
[带标题的链接](https://openai.com "悬停提示文字")
```

渲染效果：

[OpenAI](https://openai.com)
[带标题的链接](https://openai.com "悬停提示文字")

### 引用式链接

源码：

```markdown
我喜欢用 [Markdown][md] 写作，[MDX][mdx] 也不错。

[md]: https://commonmark.org
[mdx]: https://mdxjs.com "MDX 官网"
```

渲染效果：

我喜欢用 [Markdown][md] 写作，[MDX][mdx] 也不错。

[md]: https://commonmark.org
[mdx]: https://mdxjs.com "MDX 官网"

### 自动链接

源码：

```markdown
<https://commonmark.org>
<email@example.com>
```

渲染效果：

<https://commonmark.org>
<email@example.com>

> 裸 URL（`https://...` 不带尖括号）自动识别是 **GFM 扩展**，纯 CommonMark 不认。

---

## 九、图片

### 基础语法

源码：

```markdown
![替代文本](https://placehold.co/600x200/png "可选标题")
```

渲染效果：

![替代文本](https://placehold.co/600x200/png "可选标题")

### 引用式图片

源码：

```markdown
![logo][pic]

[pic]: https://placehold.co/200x100/png
```

渲染效果：

![logo][pic]

[pic]: https://placehold.co/200x100/png

### 带链接的图片

源码：

```markdown
[![点击跳转](https://placehold.co/300x100/png)](https://example.com)
```

---

## 十、转义与实体

### 反斜杠转义

CommonMark 规定以下字符可被 `\` 转义：

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

示例：

- 想显示星号：`*` 写为 `\*` → \* 而不是 *斜体*
- 想显示反引号：用双反引号包裹 `` `` ` `` ``

### HTML 字符实体

源码：

```markdown
&copy; &reg; &trade; &#9829; &#x1F600;
```

渲染效果：

&copy; &reg; &trade; &#9829; &#x1F600;

---

## 十一、HTML 混排

Markdown 允许直接嵌入原始 HTML（块级或行内），渲染时原样保留：

源码：

```markdown
<div style="border: 2px solid #ccc; padding: 12px; border-radius: 8px;">
  <p>这是一个 <strong>HTML 块</strong>，里面可以放任何标签。</p>
  <button onclick="alert('hi')">点我</button>
</div>
```

渲染效果（在支持的渲染器中）：

<div style="border: 2px solid #ccc; padding: 12px; border-radius: 8px;">
  <p>这是一个 <strong>HTML 块</strong>，里面可以放任何标签。</p>
  <button onclick="alert('hi')">点我</button>
</div>

> **GFM 会过滤危险 HTML**（如 `<script>`、`<style>`、`onclick`），CommonMark 规范则原样保留。

---

## 十二、GFM 扩展语法

GitHub Flavored Markdown 在 CommonMark 基础上增加：

### 12.1 表格

源码：

```markdown
| 左对齐 | 居中对齐 | 右对齐 |
|:-------|:--------:|-------:|
| 单元格 | 单元格   |   100  |
| 第二行 | 内容     |    42  |
| 多行   | 可含 `code` |  3.14 |
```

渲染效果：

| 左对齐 | 居中对齐 | 右对齐 |
|:-------|:--------:|-------:|
| 单元格 | 单元格   |   100  |
| 第二行 | 内容     |    42  |
| 多行   | 可含 `code` |  3.14 |

> 对齐靠第二行的 `:` 位置决定：`:---` 左、`---:` 右、`:---:` 居中。

### 12.2 删除线

源码：

```markdown
~~这段会被划掉~~，但 ~~删除~~ 不是 ~单个~ 就行。
```

渲染效果：

~~这段会被划掉~~，但 ~~删除~~ 不是 ~单个~ 就行。

### 12.3 任务列表

源码：

```markdown
- [ ] 起草方案
- [x] 完成调研
- [ ] 编写代码
  - [x] 设计数据结构
  - [ ] 实现核心逻辑
```

渲染效果：

- [ ] 起草方案
- [x] 完成调研
- [ ] 编写代码
  - [x] 设计数据结构
  - [ ] 实现核心逻辑

### 12.4 表情符号（Emoji 短码）

源码：

```markdown
:smile: :heart: :rocket: :tada: :bug: :fire:
```

渲染效果（GitHub 上）：

:smile: :heart: :rocket: :tada: :bug: :fire:

> Emoji 短码是 **GitHub 平台特性**，不是 GFM 规范强制项，其他渲染器可能原样显示文本。

### 12.5 提及与引用

源码：

```markdown
@username 会被链接到用户主页
#123 会被链接到 Issue 123
```

> 这是 GitHub **平台层**行为，离开 GitHub 就只是普通文本。

### 12.6 数学公式（GFM + MathJax/KaTeX 扩展）

源码（依赖渲染器支持）：

```latex
行内公式：$E = mc^2$

块级公式：
$$
\int_{-\infty}^{\infty} e^{-x^2} \, dx = \sqrt{\pi}
$$
```

---

## 十三、Pandoc / 学术扩展

以下特性需要 **Pandoc** 或 **MultiMarkdown** 等扩展方言支持。

### 13.1 脚注

源码：

```markdown
这里有一个脚注引用[^1]，还有另一个[^note]。

[^1]: 这是第一个脚注的内容。
[^note]: 这是命名脚注，可以包含**格式**、`代码`甚至多段。

    第二段落仍属于脚注。
```

渲染效果（Pandoc 输出）：

这里有一个脚注引用[^1]，还有另一个[^note]。

[^1]: 这是第一个脚注的内容。
[^note]: 这是命名脚注，可以包含**格式**、`代码`甚至多段。

    第二段落仍属于脚注。

### 13.2 文献引用（BibTeX + CSL）

源码：

```markdown
根据 @doe2020 的研究，这一现象早有记载 [see @smith2019, pp. 23-25]。

# References
::: {#refs}
:::
```

> 需要配合 `pandoc-citeproc` 和 `.bib` 文献库使用，输出时自动生成参考文献列表。

### 13.3 自定义 ID 与属性

源码（Pandoc 风格）：

```markdown
### 我的标题 {#custom-id .warning key=value}

[跳转到那里](#custom-id)
```

### 13.4 带编号的定理/示例环境

源码：

```markdown
::: {.theorem #pythagoras}
对于任意直角三角形，有 $a^2 + b^2 = c^2$。
:::

::: {.proof}
构造一个边长为 $a+b$ 的正方形……
:::
```

### 13.5 上标 / 下标

源码：

```markdown
水分子的公式是 H~2~O。
爱因斯坦方程：E = mc^2^。
```

渲染效果：H~2~O，E = mc^2^（需 Pandoc 扩展）。

### 13.6 YAML Frontmatter

源码（常见于静态站点生成器）：

```yaml
---
title: "我的文章"
author: "张三"
date: 2026-08-12
tags: [markdown, 语法, 参考]
---
```

---

## 十四、方言兼容速查表

下表汇总「哪种方言支持哪种语法」，打 ✅ 表示原生支持，❌ 表示不支持，⚠️ 表示需扩展/平台支持。

| 语法特性 | CommonMark | GFM | Pandoc | MultiMD | MD Extra |
|---|:---:|:---:|:---:|:---:|:---:|
| ATX 标题 `#` | ✅ | ✅ | ✅ | ✅ | ✅ |
| Setext 标题 | ✅ | ✅ | ✅ | ✅ | ✅ |
| 段落 / 硬换行 | ✅ | ✅ | ✅ | ✅ | ✅ |
| 斜体 / 粗体 | ✅ | ✅ | ✅ | ✅ | ✅ |
| 粗斜体 | ✅ | ✅ | ✅ | ✅ | ✅ |
| 行内代码 | ✅ | ✅ | ✅ | ✅ | ✅ |
| 围栏代码块 | ✅ | ✅ | ✅ | ✅ | ✅ |
| 缩进代码块 | ✅ | ✅ | ✅ | ✅ | ✅ |
| 有序 / 无序列表 | ✅ | ✅ | ✅ | ✅ | ✅ |
| 嵌套列表 | ✅ | ✅ | ✅ | ✅ | ✅ |
| 引用块 | ✅ | ✅ | ✅ | ✅ | ✅ |
| 水平线 | ✅ | ✅ | ✅ | ✅ | ✅ |
| 行内链接 | ✅ | ✅ | ✅ | ✅ | ✅ |
| 引用式链接 | ✅ | ✅ | ✅ | ✅ | ✅ |
| 自动链接 `<>` | ✅ | ✅ | ✅ | ✅ | ✅ |
| 裸 URL 自动链 | ❌ | ✅ | ⚠️ | ❌ | ✅ |
| 图片 | ✅ | ✅ | ✅ | ✅ | ✅ |
| 转义字符 | ✅ | ✅ | ✅ | ✅ | ✅ |
| HTML 块透传 | ✅ | ⚠️过滤 | ✅ | ✅ | ✅ |
| 表格 | ❌ | ✅ | ✅ | ✅ | ✅ |
| 任务列表 | ❌ | ✅ | ❌ | ❌ | ❌ |
| 删除线 | ❌ | ✅ | ✅ | ❌ | ❌ |
| Emoji 短码 | ❌ | ⚠️平台 | ❌ | ❌ | ❌ |
| @提及 / #issue | ❌ | ⚠️平台 | ❌ | ❌ | ❌ |
| 脚注 | ❌ | ⚠️实验 | ✅ | ✅ | ✅ |
| 定义列表 | ❌ | ❌ | ✅ | ✅ | ✅ |
| 数学公式 | ❌ | ⚠️扩展 | ✅ | ✅ | ❌ |
| 上标 / 下标 | ❌ | ❌ | ✅ | ❌ | ✅ |
| 自定义属性 | ❌ | ❌ | ✅ | ⚠️ | ✅ |
| YAML Frontmatter | ❌ | ⚠️工具 | ✅ | ✅ | ❌ |
| 文献引用 | ❌ | ❌ | ✅ | ❌ | ❌ |
| 高亮 ==text== | ❌ | ❌ | ⚠️ | ❌ | ❌ |
| 双向链接 [[]] | ❌ | ❌ | ❌ | ❌ | ❌ |

> **图例**：✅ 原生支持 ｜ ⚠️ 需扩展或仅平台层 ｜ ❌ 不支持
> 双向链接 `[[]]` 是 Obsidian / Roam 等笔记工具私有语法，不属于任何标准方言。

---

## 附录：CommonMark 行内定界符规则要点

CommonMark 用**定界符栈算法**处理强调，避免老实现的歧义：

1. `*` 和 `_` 都可作定界符，但 `_` 在单词内部**不**触发（如 `a_b_c` 不是强调）。
2. 定界符的"长度"（连续星号个数）决定它是 `em`（1）、`strong`（2）还是 `emph+strong`（3）。
3. 左定界符和右定界符必须**同类型同长度**才能匹配。
4. 优先级：先匹配更长的定界符（strong 优先于 em）。

示例：

| 源码 | 渲染 |
|---|---|
| `***abc***` | ***abc***（粗斜体） |
| `**abc**` | **abc**（粗体） |
| `*abc*` | *abc*（斜体） |
| `**abc* def*` | **abc* def*（左 greedy，注意结果） |
| `a*b*c` | a*b*c（单词内不下划线规则类比） |

---

## 附录：GFM 与 CommonMark 的关键差异清单

1. **裸 URL 自动链接**：GFM 自动，`https://x.com` → 链接；CM 需写 `<https://x.com>`。
2. **换行行为**：GFM 在 Issue/PR 评论框里"单换行 = `<br>`"，README 仍遵循 CM 两空格规则。
3. **HTML 过滤**：GFM 移除 `<script>` `<style>` `on*` 事件等；CM 原样保留。
4. **表格**：GFM 支持管道表格，CM 不支持（会被当普通文本）。
5. **任务列表**：GFM `- [ ]` 渲染为可勾选框；CM 视为普通列表项。
6. **删除线**：GFM `~~x~~` → `<del>`；CM 中 `~~` 只是普通标点。
7. **围栏代码块 info string**：GFM 把 ` ```js ` 中的 `js` 用作语法高亮提示；CM 只当普通文本。
8. **@提及 / #issue**：GFM 平台层自动转链接；CM 完全无此概念。

---

## 附录：实战建议

- **写跨平台文档** → 以 **CommonMark 为最小子集**，只在确定环境（如 GitHub README）时才用 GFM 表格/任务列表。
- **做解析器 / 测试工具** → 对着 **CommonMark spec + 官方测试套件**实现，再叠加扩展。
- **学术 / 出版输出** → 直接用 **Pandoc Markdown**，一次编写转 PDF / DOCX / EPUB。
- **技术社区内容** → **GFM 是默认普通话**，但注意 `@`、`:emoji:`、`#123` 是平台行为不是规范强制项。
- **个人知识库** → 选 Obsidian / Logseq 等，接受其私有语法 `[[链接]]`、`==高亮==` 不可移植的代价。

---

> 📌 **本文档本身就是一个合规的 Markdown 文件**，可直接用任何 CommonMark / GFM 渲染器打开验证效果。