Markdown 是什么以及为什么它依然重要
Markdown 由 John Gruber 在 2004 年创建，最初目的是让人们用纯文本写出格式丰富的文档，而不需要学习 HTML。二十多年过去了，它不仅没有被淘汰，反而成为了开发者世界的通用语言——GitHub README、技术博客、文档站点、甚至聊天应用都支持它。
它流行的原因很简单：纯文本永远不会过时。你的 .md 文件在任何编辑器里都能打开，用 Git 做版本控制完美无缺（diff 清晰可读），而且学习成本极低——大多数语法在 10 分钟内就能掌握。
2026 年的现实是：你不需要掌握"一种" Markdown，而是需要了解几种方言之间的差异。CommonMark 是基础规范，GitHub Flavored Markdown（GFM）添加了表格和任务列表，而 MDX 则允许你在 Markdown 里嵌入 React 组件。本指南以 GFM 为主线，同时标注各方言的差异。
基础文本格式：标题、段落与强调
标题用 # 号标记，从 # 到 ###### 对应 H1 到 H6。最佳实践是每个文档只用一个 H1（通常是标题），然后用 H2 和 H3 组织内容层级。不要跳过层级——直接从 H2 跳到 H4 会让屏幕阅读器用户困惑，也对 SEO 不利。
段落之间需要一个空行来分隔。仅仅换行不会创建新段落——这是很多新手的困惑点。如果你需要行内换行（<br>），在行尾加两个空格再回车，或者使用反斜杠 \。
强调语法：*斜体* 或 _斜体_，**粗体** 或 __粗体__，***粗斜体***。删除线用 ~~文本~~（GFM 扩展）。建议统一使用星号而非下划线，因为下划线在单词中间时（如 some_variable_name）的解析行为在不同解析器之间不一致。
水平分割线用三个或更多的 ---、*** 或 ___ 来创建。它们在视觉上分隔文档的大块内容，适合在长文档中标记主题转换。
# 文档标题（H1——每篇文档只用一次）
## 主要章节（H2）
### 子章节（H3）
这是一个段落。连续文字属于同一段落。
这是另一个段落——上面有空行分隔。
**粗体文本**用于强调重点。
*斜体文本*用于术语或轻度强调。
~~删除线~~表示废弃或更正的内容。
---
上面的横线分隔了两个不同的话题。链接、图片与引用
行内链接的格式是 [显示文本](URL "可选标题")。引用式链接把 URL 定义放在文档底部：[显示文本][ref-id] 然后 [ref-id]: URL。引用式链接让长文档更易读，特别是同一个链接出现多次时——修改一处即可全部更新。
图片语法和链接几乎一样，只是前面多了一个感叹号：。替代文本（alt text）不是可选装饰——它对无障碍访问至关重要，屏幕阅读器会朗读这段文字。描述图片内容而非文件名：写"柱状图显示2025年各季度营收增长"而非"chart.png"。
块引用用 > 开头。嵌套引用用 >> 。在 GitHub 上，你可以用特殊的告示语法来创建彩色的提示框：> [!NOTE]、> [!TIP]、> [!IMPORTANT]、> [!WARNING]、> [!CAUTION]。这些在文档中非常有用，能让关键信息从正文中脱颖而出。
自动链接：在 GFM 中，裸 URL 会自动变成可点击的链接。但在正式文档中，建议始终使用显式的链接语法并提供有意义的显示文本——"查看配置文档"比一长串 URL 更友好。
<!-- 行内链接 -->
[访问 GitHub](https://github.com "GitHub 首页")
<!-- 引用式链接——适合反复引用同一个 URL -->
阅读 [安装指南][install] 和 [配置文档][config]。
[install]: https://example.com/install
[config]: https://example.com/config
<!-- 图片（注意 alt 文本的写法） -->
<!-- GitHub 告示语法 -->
> [!WARNING]
> 此操作不可撤销，请确认后再执行。列表与任务清单
无序列表用 -、* 或 + 开头（建议统一用 -）。有序列表用数字加点（1.、2.、3.）。Markdown 其实不关心你的数字是否连续——即使全写 1. 1. 1.，渲染时也会自动编号。但为了源文件可读性，建议手动维护正确的编号。
列表嵌套通过缩进实现。标准缩进是 4 个空格或 1 个 Tab，但 GFM 接受 2 个空格。列表项中可以包含段落、代码块甚至其他列表——只要正确缩进即可。
任务列表（GFM 扩展）用 - [ ] 表示未完成、- [x] 表示已完成。在 GitHub Issues 和 PR 描述中使用任务列表时，GitHub 会自动在标题旁边显示完成进度（如"2/5"）。这是一个非常实用的项目管理技巧。
定义列表不是标准 Markdown 的一部分，但某些扩展（如 PHP Markdown Extra 和某些静态站点生成器）支持。如果需要跨平台兼容，用加粗文本模拟术语，紧接着普通段落作为定义。
## 发布检查清单
- [x] 代码审查通过
- [x] 单元测试全部绿灯
- [ ] 更新 CHANGELOG
- [ ] 添加数据库迁移脚本
## 嵌套列表示例
1. 前端优化
- 压缩图片资源
- 启用代码分割
- 配置缓存策略
2. 后端优化
- 添加数据库索引
- 实现 Redis 缓存
- 优化 N+1 查询代码块与语法高亮
行内代码用单个反引号包裹：`console.log()`。如果代码本身包含反引号，用双反引号包裹：`` `hello` ``。代码块用三个反引号（```）开始和结束，开始行后面跟语言标识符来启用语法高亮。
常用的语言标识符：javascript（或 js）、typescript（或 ts）、python、bash（或 shell）、json、html、css、sql、yaml、markdown（或 md）。GitHub 支持超过 500 种语言标识符——如果不确定，查阅 linguist 项目的语言列表。
代码块中的缩进：反引号围栏内的代码按原样渲染，不需要额外缩进。但如果代码块在列表项内部，整个围栏需要与列表内容对齐（通常缩进 4 个空格）。这是 Markdown 代码块最容易出错的地方之一。
Diff 高亮：使用 ```diff 作为语言标识，在行首加 + 或 - 来显示代码变更。GitHub 也支持在代码审查中用建议语法（```suggestion）直接提出修改——审查者点一下按钮就能应用修改。
行内代码：使用 `Array.from()` 将类数组转为真正的数组。
```typescript
// 带类型注解的函数示例
function debounce<T extends (...args: unknown[]) => void>(
fn: T,
delay: number
): (...args: Parameters<T>) => void {
let timer: ReturnType<typeof setTimeout>;
return (...args) => {
clearTimeout(timer);
timer = setTimeout(() => fn(...args), delay);
};
}
```
```diff
- const API_URL = 'http://localhost:3000';
+ const API_URL = process.env.NEXT_PUBLIC_API_URL;
```表格与数据展示
GFM 表格用管道符 | 分隔列，用破折号 --- 分隔表头和内容。对齐方式通过冒号控制：:--- 左对齐、:---: 居中、---: 右对齐。数字列通常右对齐，文本列左对齐——这符合数据表格的阅读习惯。
表格的局限性：标准 GFM 表格不支持单元格合并、多行内容或嵌套列表。如果需要复杂表格，要么用 HTML（GitHub 支持在 Markdown 中嵌入 HTML 表格），要么重新考虑是否应该用表格来展示这些数据。
维护表格源码的技巧：列宽不需要对齐，|标题|内容| 和 | 标题 | 内容 | 的渲染结果完全相同。但对齐后的源码更容易阅读和维护。VS Code 的 Markdown Table Formatter 扩展可以一键对齐。
何时不用表格：如果表格超过 5 列或内容很长，在窄屏上会溢出或需要横向滚动。考虑改用列表或嵌套的标题+段落结构来展示相同信息。可访问性指南也建议避免过于复杂的表格。
| 格式 | 扩展名 | 用途 | 人类可读 |
| :----- | :----: | :----------------------- | -------: |
| JSON | .json | API 传输、配置文件 | 是 |
| YAML | .yml | DevOps 配置、CI/CD | 是 |
| TOML | .toml | 应用配置（Rust 生态） | 是 |
| CSV | .csv | 表格数据交换 | 部分 |
| Protobuf | .proto | 高性能 RPC 序列化 | 否 |GFM 扩展：脚注、数学公式与 Mermaid 图表
脚注语法：在正文中用 [^1] 标记，在文档任意位置用 [^1]: 说明内容 定义脚注内容。渲染时脚注会自动编号并集中显示在页面底部。这对学术性文档或需要补充说明但不想打断阅读流的场景非常有用。
数学公式：GitHub 从 2022 年开始支持 LaTeX 语法。行内公式用 $E = mc^2$，块级公式用 $$ 包裹。支持大部分 LaTeX 数学命令——求和、积分、矩阵、希腊字母等。注意 $ 符号如果在普通文本中出现（比如价格 $100），不会被误解析为公式边界，因为公式需要紧贴文本无空格。
Mermaid 图表：用 ```mermaid 代码块来绘制流程图、序列图、甘特图、ER 图等。GitHub 原生渲染这些图表，不需要额外的图片文件。这意味着图表和代码一起版本控制，修改时 diff 清晰可见——这比维护一堆 PNG 截图好太多了。
告示框（Alerts）：> [!NOTE]、> [!TIP]、> [!IMPORTANT]、> [!WARNING]、> [!CAUTION] 五种级别，从信息性到警告逐级递增。每种都有不同的颜色和图标。在技术文档中合理使用它们，能显著提升可浏览性——读者一扫就能定位关键信息。
<!-- 脚注 -->
Markdown 由 Gruber 创建[^1]，后来被 CommonMark 标准化[^2]。
[^1]: John Gruber, 2004. https://daringfireball.net/projects/markdown/
[^2]: CommonMark 规范: https://spec.commonmark.org/
<!-- 数学公式 -->
二次方程求根公式：$$x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}$$
<!-- Mermaid 流程图 -->
```mermaid
graph LR
A[提交代码] --> B{CI 通过?}
B -->|是| C[自动部署到预发布]
B -->|否| D[通知开发者修复]
C --> E[手动确认后部署生产]
```Markdown 写作最佳实践
一句一行（One Sentence Per Line）：不要把整个段落写在一行里。每句话独占一行，这样 Git diff 能精确显示哪句被修改了，代码审查时也更容易逐句评论。渲染时连续的行会合并为段落，所以最终效果不变。
语义化使用格式：粗体用于用户必须注意的关键信息，斜体用于首次出现的术语或轻度强调，代码格式用于代码和命令行输入。不要仅仅为了视觉效果滥用格式——屏幕阅读器会对每种格式做不同的语音处理。
文档结构的金字塔原则：把最重要的信息放在文档开头。README 应该前三行就说清楚这个项目是什么、解决什么问题。详细的安装步骤、API 文档和贡献指南放在后面。读者的注意力呈漏斗形——越往下越少人读到。
链接维护：对外部链接定期做死链检查（用 markdown-link-check 等工具）。对项目内部文件的引用用相对路径而非绝对 URL——这样即使域名变了或仓库被 fork，链接依然有效。日期容易过时，除非必要，避免在文档中写"目前"、"最新"等相对时间描述。