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

Updated 8/12/2026, 10:02:18 AM

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

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

目录

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

一、标题

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

ATX 风格（推荐）

源码：

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

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

Setext 风格（仅一级、二级）

源码：

一级标题
========

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

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

二、段落与换行

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

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

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

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

三、文本格式化（行内）

混合示例：

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

四、引用块

源码：

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

渲染效果：

这是一级引用。

可以有多段，段落间用空行 + 大于号分隔。

这是嵌套引用（二级）。

引用里还能放标题

• 以及列表
• 甚至代码块

五、列表

无序列表

源码：

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

渲染效果：

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

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

有序列表

源码：

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

渲染效果：

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

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

任务列表（GFM）

源码：

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

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

• 未完成的任务
• 已完成的任务
• 另一个待办
  • 子任务已完成

定义列表（Pandoc / MultiMarkdown）

源码（Pandoc 风格）：

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

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

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

六、代码

行内代码

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

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

围栏代码块（推荐）

源码：

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

渲染效果：

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

缩进代码块（原始风格）

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

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

渲染效果：

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

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

七、水平线

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

源码：

---

***

___

渲染效果：

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

八、链接

行内链接

源码：

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

渲染效果：

OpenAI
带标题的链接

引用式链接

源码：

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

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

渲染效果：

我喜欢用 Markdown 写作，MDX 也不错。

自动链接

源码：

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

渲染效果：

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

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

九、图片

基础语法

源码：

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

渲染效果：

引用式图片

源码：

![logo][pic]

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

渲染效果：

带链接的图片

源码：

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

十、转义与实体

反斜杠转义

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

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

示例：

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

HTML 字符实体

源码：

© ® ™ ♥ 😀

渲染效果：

© ® ™ ♥ 😀

十一、HTML 混排

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

源码：

<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 表格

源码：

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

渲染效果：

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

12.2 删除线

源码：

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

渲染效果：

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

12.3 任务列表

源码：

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

渲染效果：

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

12.4 表情符号（Emoji 短码）

源码：

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

渲染效果（GitHub 上）：

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

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

12.5 提及与引用

源码：

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

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

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

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

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

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

十三、Pandoc / 学术扩展

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

13.1 脚注

源码：

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

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

    第二段落仍属于脚注。

渲染效果（Pandoc 输出）：

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

第二段落仍属于脚注。

13.2 文献引用（BibTeX + CSL）

源码：

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

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

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

13.3 自定义 ID 与属性

源码（Pandoc 风格）：

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

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

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

源码：

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

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

13.5 上标 / 下标

源码：

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

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

13.6 YAML Frontmatter

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

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

十四、方言兼容速查表

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

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

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

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

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

示例：

附录：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 渲染器打开验证效果。