Markdown 语法速查表 - Markdown 常用语法大全
Markdown 的麻烦不在语法难，而在同一份文本在不同平台渲染成不同结果：GitHub 渲染表格，文档站不渲染；某些平台不支持任务列表，某些平台把行内 HTML 直接过滤掉。本表把各平台普遍支持的写法与各自的扩展放在一起对照，按标题、文本格式、列表、代码块、链接与图片、表格与分隔线组织，重点标出哪些是通用语法、哪些只在部分平台生效。判断该用哪种写法有一致标准：能用通用语法就别用扩展，因为扩展换来的一点便利会在迁移时变成返工；确实需要扩展时（任务列表、自动链接），至少确认目标平台支持，并准备一个纯文本回退。文档站与仓库 README 之间来回搬运是变形的高发场景，尤其表格内的换行、代码块里嵌代码、以及链接中包含特殊字符这三处最容易出问题。
标题 Heading 5
# H1## H2### H3标题
===标题
---文本格式 Text Style 7
**粗体***斜体****粗斜体***~~删除线~~`行内代码`> 引用文本> > 嵌套引用列表 List 5
- 无序列表项1. 有序列表项- [ ] 待办- [x] 已完成 - 缩进子项代码块 Code Block 4
```python``` 4空格缩进代码```{bash eval=true}链接与图片 Link & Image 5
[文本](https://example.com)[文本](https://example.com "标题")[文本][ref]
[ref]: https://example.com[文本](#锚点id)表格与分隔线 Table & HR 5
---| 列1 | 列2 |
| --- | --- |
| a | b || :--- || :---: || ---: |提示
- 表格内换行用 <br>，Markdown 表格不支持直接换行。
- 代码块内反引号冲突时，可用更多的反引号围栏（如 ~~~~ 包裹含 ``` 的内容）。
- GFM（GitHub Flavored Markdown）支持任务列表、删除线、自动链接和表格，比标准 Markdown 功能多。
- 标题层级不要跳级（用完 h2 直接接 h4），很多文档站据此生成目录，跳跃会导致锚点目录缺项。
- 图片统一写相对路径
./assets/x.png并随仓库提交，否则脱离仓库单独分享文档时图片全部失效。 - 表格列数较多时改用定义列表或分节描述：表格超过五六列后单元格换行会在窄屏上挤成一团，可读性反而下降。
常见问题
markdown 里用相对路径的图片发布后打不开怎么办?
相对路径相对的是 Markdown 文件所在目录，例如 ./images 下的图用 ，发布前需确认图片一并部署且站点没有重写 URL。GitHub 仓库的相对路径可行但大小写敏感；文档站若走图床渲染，应改用完整 URL 以免相对路径失效。
markdown 表格单元格里想放竖线或换行怎么办?
表格列由竖线 | 分隔，单元格里要显示字面竖线就写成 \| 转义。单元格内换行可用 HTML 的 <br>；原生软换行会在表格内合并成空格。建议保持单元格内容简短，复杂排版改用引用块或列表。
markdown 代码块要指定语言吗，有哪些通用写法?
用三个反引号包住代码，紧跟语言标识即可高亮，如 ```javascript。有些平台也认四个空格缩进代码块，行内代码用单个反引号。不同主题支持的语言名略有差异，但 javascript、typescript、bash、json、python 这些通用标识多数解析器都能识别。
markdown 的长链接和引用式链接怎么写?
行内式直接 [文本](https://...)，但长 URL 会让文档难读。引用式先在链接列表定义 [key]: https://...，再用 [文本][key] 引用，一处定义、多处复用，改写一处即可全局生效。裸 URL 在不少平台会自动转成链接。
为什么我写的 markdown 本地预览正常、发到 GitHub 就变形?
各平台解析 Markdown 的子集不同：GitHub 用 GFM，支持任务列表、自动链接、@提及、表格高亮，但对空行、缩进更严格，并会清洗部分原始 HTML。本地预览主题与换行折叠也各有差异。最稳妥是只用方括号、星号、反引号等通用语法，发布前用目标平台的预览先看一遍。
由 巧匠 维护
公开更新于 2026年7月21日，内容持续校对官方文档。