这一期我们直击 Markdown 的四大核心砖块：标题、列表、代码块、链接 & 图片。
这些元素占日常写作 80%+ 使用率，但也藏着最多“渲染崩坏”的坑。
我们以 CommonMark（最严格标准）+ GFM（GitHub Flavored Markdown，2026 年最主流方言）为基准，给你最实用的速查表 + 避坑指南。
所有示例都已在 GitHub / VS Code / Obsidian / VitePress 实测通过。
一、Headings（标题）速查 & 常见坑
速查表
| 级别 | Markdown 写法 | 推荐风格 | 渲染结果 |
|---|---|---|---|
| H1 | # 标题一级 | 强烈推荐 | 大标题 |
| H2 | ## 标题二级 | 强烈推荐 | 次级标题 |
| H3 | ### 标题三级 | 推荐 | 小节标题 |
| H4–6 | #### / ##### / ###### | 根据需要 | 更细层级 |
| Alt | 标题一级\n========== | 只用于 H1 | H1 |
| Alt | 标题二级\n---------- | 只用于 H2 | H2 |
必须遵守的规范（CommonMark 严格要求）：
#后必须有一个空格（#标题会解析失败或渲染成纯文本）- 建议在标题前后各空一行（提升可读性 & 避免与上方内容粘连）
- 不要跳级（H1 → H3 跳过 H2，会让屏幕阅读器和 SEO 混乱）
常见坑 & 正确写法
| 错误写法 | 为什么崩？ | 正确写法 | 说明 |
|---|---|---|---|
#标题一级 | 缺少空格 → 很多渲染器直接忽略或当文本 | # 标题一级 | 强制空格 |
###标题 | 同上 | ### 标题 | — |
# 标题\n紧挨着正文 | 标题与段落粘连，阅读体验差 | # 标题\n\n正文... | 前后空行最佳实践 |
H1\n====（无空行） | 可能被当成普通段落 | H1\n\n======== | 上下空行更安全 |
标题里放太多 # 后缀 | 部分老渲染器会显示多余 # | 后缀可选，不写最好 | GitHub / VS Code 忽略后缀 |
小技巧：在 VS Code 用 Markdown All in One 插件，按 Ctrl+Shift+P → Markdown: Toggle Heading 一键调级别。
二、Lists（列表）速查 & 常见坑
速查表
| 类型 | 写法示例 | 备注 |
|---|---|---|
| 无序列表 | - 项目 或 * 项目 或 + 项目 | 三种符号等价，推荐统一用 - |
| 有序列表 | 1. 第一项（数字随便写，都从 1 开始） | 自动重编号 |
| 嵌套列表 | 缩进 2–4 空格（推荐 4） | — |
| 任务列表 | - [ ] 未完成 / - [x] 已完成 | GFM 专有，GitHub / Obsidian 支持 |
常见坑 & 正确写法
| 错误写法 | 为什么崩？ | 正确写法 | 说明 |
|---|---|---|---|
-项目（无空格） | 渲染成普通文本 | - 项目 | 符号后必须空格 |
1.第一项 | 同上 | 1. 第一项 | 空格必备 |
| 列表后直接接段落无缩进 | 段落被当成列表项续写 | 列表项后空一行 + 不缩进的段落 | 或缩进 4 空格作为“子段落” |
| 嵌套列表缩进不一致 | 嵌套失败或多级错位 | 统一缩进 4 空格 | 推荐 VS Code 自动格式化 |
- [x]任务（空格不对） | 任务框不渲染 | - [x] 任务 或 - [ ] 任务 | 空格位置严格：[ ] 后一个空格 |
小技巧：列表里想放多行文本？在子行缩进 4 空格（或与列表标记对齐）。
三、Code Blocks（代码块）速查 & 常见坑
速查表
| 类型 | 写法示例 | 备注 |
|---|---|---|
| 行内代码 | `console.log()` | 单反引号 |
| 缩进代码块 | 每行前面 4 空格 或 1 Tab | 老式，少用 |
| 围栏代码块 | ```js:disable-run | |
| 带文件名 | ```js:title="app.js"\n代码\n``` | 部分平台（如 VitePress）支持 |
常见坑
| 错误写法 | 问题 | 正确写法 | 说明 |
|---|---|---|---|
`多行代码` | 只渲染第一行 | 用围栏 ``` 或缩进 4 空格 | 行内代码不允许换行 |
| 围栏代码没留空行 | 与上方文本粘连 | 代码块前后各空一行 | 最佳实践 |
语言标识写错（如 javascript 而非 js） | 高亮失效 | 用常见缩写：js、ts、py、html 等 | GitHub 支持 200+ 语言标识 |
| 缩进代码块在列表里只缩 4 空格 | 被当成列表续写 | 在列表里需缩进 8 空格（或 2 Tab） | CommonMark 规则 |
四、Links & Images（链接 & 图片）速查 & 常见坑
速查表
| 类型 | 写法示例 | 备注 |
|---|---|---|
| 行内链接 | [GitHub](https://github.com) | 最常用 |
| 带标题 | [GitHub](https://github.com "Hover 提示") | 可选 title |
| 引用链接 | [GitHub][gh][gh]: https://github.com | 适合多处复用 |
| 自动链接 | <https://example.com> 或直接 https://example.com | GFM 自动转链接 |
| 图片 |  | 感叹号必备 |
| 带标题图片 |  | — |
| 引用图片 | ![Alt][img][img]: https://img.png | — |
常见坑
| 错误写法 | 问题 | 正确写法 | 说明 |
|---|---|---|---|
[链接](url) 无空格 | 部分渲染器解析失败 | [链接](url) | 括号紧挨 |
图片没写 alt  | 无障碍性差，SEO 差 |  | 总是写有意义的 alt |
相对路径写错 ./img.png | GitHub Pages / 不同平台解析不同 | 用 /img.png（根路径）或 ./img.png 相对当前 md | 测试渲染效果 |
链接里带空格 [我的 链接](url) | 部分老渲染器截断 | [我的链接](url) 或转义空格 | 推荐避免空格 |
图片链接混写  | title 被忽略或出错 | 严格按语法：alt 后 url 后可选 title | — |
小技巧：用 VS Code 的 Markdown Paste 或 Paste Image 插件，一键粘贴图片自动生成 。
总结 Checklist（复制粘贴用）
- 标题：
#后必空格，前后空行 - 列表：符号后空格，嵌套统一 4 空格
- 代码：优先围栏 ```，语言标识准确
- 链接/图片：alt 必写，路径测试渲染
- 整体：保存后在 GitHub / Obsidian 预览确认
