Markdown 速查表：GitHub-Flavored Markdown 完整语法参考

Markdown 是开发者的日常语言——GitHub README、Pull Request 描述、技术文档、笔记工具，无处不在。GitHub-Flavored Markdown（GFM）在 CommonMark 规范基础上扩展了表格、任务清单、删除线和自动链接等特性。本文是一份完整速查表。

在线实时预览 Markdown →

标题

# H1 — 页面标题
## H2 — 一级章节
### H3 — 二级章节
#### H4
##### H5
###### H6

按层级嵌套使用，H1 通常是文档标题，H2/H3 用于章节。

强调

语法	效果
`斜体` 或 `_斜体_`	斜体
`粗体` 或 `__粗体__`	粗体
`*粗斜体*`	粗斜体
`~~删除线~~`	~~删除线~~（GFM 扩展）

列表

无序列表

- 第一项
- 第二项
  - 嵌套项（两格缩进）
  - 另一个嵌套项
- 第三项

支持 -、*、+ 作为列表符号，同一列表内保持一致。

有序列表

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

实际数字不影响渲染，Markdown 会自动按顺序排列。

任务清单（GFM）

- [x] 创建仓库
- [x] 编写 README
- [ ] 添加 CI 配置
- [ ] 发布首个 Release

在 GitHub 上渲染为可交互的复选框，常用于 Issue、PR 和项目文档。

代码

行内代码

用反引号标记行内代码：`变量名`、`npm install`、`const x = 1`

围栏代码块

```javascript
function greet(name) {
  return `你好，${name}！`;
}
```

常用语言标识符：js、javascript、ts、typescript、python、py、bash、sh、go、rust、java、c、cpp、json、yaml、html、css、sql、diff、markdown 等。

纯文本块

```
不需要语法高亮的纯文本
```

链接

[链接文字](https://example.com)
[带标题的链接](https://example.com "悬停提示")
[引用式链接][ref-id]

[ref-id]: https://example.com

自动链接（GFM）

GFM 自动将裸露的 URL 和邮件地址转换为可点击链接：

https://github.com 自动变为链接
user@example.com 自动变为 mailto 链接

图片

![替代文字](image.png)
![替代文字](image.png "可选标题")
![引用式][img-ref]

[img-ref]: /path/to/image.png

图片加链接：

[![替代文字](image.png)](https://example.com)

表格（GFM）

| 列 1     | 列 2     | 列 3     |
|----------|----------|----------|
| 单元格   | 单元格   | 单元格   |
| 单元格   | 单元格   | 单元格   |

列对齐

| 左对齐   | 居中对齐 | 右对齐   |
|:---------|:--------:|---------:|
| 左       | 中       | 右       |

:--- — 左对齐（默认）
:---: — 居中对齐
---: — 右对齐

引用块

> 这是一段引用。
>
> 可以跨多个段落。

> 一级引用
>> 二级嵌套引用

分隔线

以下三种写法都能生成水平分割线：

---
***
___

脚注（GFM 扩展）

这个说法需要引用。[^1]

[^1]: 来源：某可靠参考资料，2024 年。

Markdown 中使用 HTML

大多数 Markdown 渲染器支持原始 HTML：

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

隐藏内容。在 GitHub 上，HTML 块内也支持 **Markdown** 语法。

</details>

这种用法常见于 GitHub README 的折叠区块。

转义特殊字符

用反斜杠转义 Markdown 语法字符：

\*不是斜体\*
\`不是代码\`
\# 不是标题

可转义字符：\、`、*、_、{、}、[、]、(、)、#、+、-、.、!

GitHub 专属扩展

提及（@mention）

@用户名 — 提及某个用户
@org/team — 提及某个团队

Issue 和 PR 引用

#123          — 链接到 Issue 或 PR #123
user/repo#123 — 跨仓库引用
SHA           — 链接到某个提交（7 位以上）

Emoji（GFM）

:rocket: :white_check_mark: :warning: :tada:

常用 Emoji 代码：

:warning: — ⚠️
:white_check_mark: — ✅
:x: — ❌
:rocket: — 🚀
:memo: — 📝

CommonMark vs GFM 对比

特性	CommonMark	GFM
段落、标题、列表	✅	✅
围栏代码块	✅	✅
强制换行	✅	✅
表格	❌	✅
任务清单	❌	✅
删除线	❌	✅
自动链接	部分	✅
@提及 / Issue 引用	❌	✅

面向 GitHub 写作时可以放心使用 GFM 特性。追求最大兼容性（各类静态站点生成器等）时，建议坚持 CommonMark 规范。

README 最佳实践

一份完善的 GitHub README 通常包含：

项目名称和一句话描述
状态徽章 — 构建状态、版本号、许可证
安装说明 — 包含命令的代码块
使用示例 — 简短的代码示例
API 参考 — 关键选项的表格或列表
贡献指南 — 链接到 CONTRIBUTING.md
许可证 — 一行说明许可证类型

实时预览 Markdown

在没有实时预览的情况下写 Markdown 容易出错，尤其是表格和嵌套列表。将内容粘贴到预览工具中，提交前先确认渲染效果。

使用在线 Markdown 预览工具 → — 实时渲染 GitHub-Flavored Markdown，无需账号。

标题

强调

列表