Markdown 进阶（GitHub 扩展）
这是系列的最后一篇，讲 GitHub Flavored Markdown（GFM）和现代 Markdown 引擎扩展出来的高级语法——警告框、脚注、Mermaid 流程图、数学公式、折叠区块。这些不在原版 CommonMark 规范里，但 GitHub、GitLab、Obsidian、VuePress 等主流引擎都已支持。
1. 警告框（Alerts / Admonitions）
2023 年 GitHub 正式支持的语法——在引用里用 [!TYPE] 标记，渲染成带颜色和图标的提示框：
> [!NOTE]
> 这是一个提示框（蓝色）
> [!TIP]
> 这是一个小贴士（绿色）
> [!IMPORTANT]
> 这是重要信息（紫色）
> [!WARNING]
> 这是警告（黄色）
> [!CAUTION]
> 这是危险操作（红色）
五种类型对应五种颜色，语义清晰、视觉抢眼，是写文档的神器。Obsidian、VitePress 等也支持类似语法（细节略不同）。
2. 脚注（Footnotes）
脚注让正文不被引文打断——正文里放标记，解释集中到底部：
正文里用标记 [^1] 引用脚注。
也可以用文字标记 [^note]。
点击标记会跳到底部脚注定义。
[^1]: 这是脚注的内容，会渲染到文档底部。
[^note]: 标识符可以是任意字符串。
渲染时标记会变成可点击的上标数字，跳到底部脚注定义；底部脚注旁有"返回"箭头。学术写作、技术文档的引用必备。
3. Mermaid 图表
用 mermaid 语言标识的代码块，会渲染成流程图、时序图、甘特图等：
```mermaid
graph TD
A[开始] --> B{是否登录?}
B -->|是| C[进入主页]
B -->|否| D[跳转登录]
D --> C
```
```mermaid
sequenceDiagram
participant U as 用户
participant S as 服务器
U->>S: 发送请求
S-->>U: 返回响应
```
支持图类型：flowchart、sequence、class、state、gantt、pie、gitGraph 等。
Mermaid 是用文本画图的工具——源码是纯文本，渲染成 SVG，可版本控制。GitHub、GitLab、Notion、Obsidian 都内置支持。
4. 数学公式（Math / LaTeX）
用 $...$ 写行内公式，$$...$$ 写块级公式，语法同 LaTeX：
行内公式：$E = mc^2$ 嵌在句子里。
块级公式独占一行：
$$
\int_0^1 x^2 \, dx = \frac{1}{3}
$$
$$
\sum_{i=1}^{n} i = \frac{n(n+1)}{2}
$$
GitHub 使用 MathJax 渲染，语法同 LaTeX。
GitHub 在 2022 年正式支持数学公式，对写论文、算法、统计的技术博客非常友好。
5. 提及与引用（Mentions & References）
GitHub 私有语法——@ 提及用户、# 引用 Issue：
@username 提及 GitHub 用户（会发通知）
#123 引用 Issue 或 PR 编号（自动变链接）
@org/team 提及整个团队
commit SHA 前缀（7 位以上）会自动变链接
这些只在 GitHub 渲染时生效，发布到其他平台会显示为字面文本。
6. 表情（Emoji Shortcodes）
用冒号包裹的 shortcode 插入表情：
GitHub 支持 shortcode 表情：
:smile: :rocket: :+1: :heart: :tada:
:bug: :fire: :tada: :100: :checkered_flag:
完整列表搜索 "emoji cheat sheet"。
比直接贴 Unicode 表情更易记，也方便搜索。GitHub、Slack、Discord 都支持。
7. 任务列表回顾
- [x] 写文档
- [ ] 发布
- [ ] 收集反馈
（任务列表在 GFM 章节 已详细讲过）
已在列表那篇详细讲过，这里不重复。要点：方括号里空格表示未完成、字母 x 表示已完成。
8. 自动目录（TOC）
长文档必备。两种做法：
自动目录（部分引擎支持，如 Obsidian、VuePress）：
```toc
```
或手动写目录（GitHub 推荐方式）：
## 目录
- [简介](#简介)
- [安装](#安装)
- [使用](#使用)
锚点规则：标题转小写、空格转 -、移除标点。
9. HTML 注释（隐藏内容）
想在源码里留笔记、TODO，但渲染时不显示——用 HTML 注释：
<!-- 这是一条 HTML 注释，渲染时不显示 -->
但源码里可以看到，适合留笔记、TODO、内部说明。
<!-- TODO: 这一段需要补充示例 -->
<!-- FIXME: 这里数字待核对 -->
这种用法在多人协作的项目里很常见——给协作者看，不给读者看。
10. 折叠区块（Details）
用 HTML 的 <details> 标签实现折叠——长文档的"次要细节"可以默认隐藏：
<details>
<summary>点击展开详细说明</summary>
这里是被折叠的内容，默认不显示。
- 可以放任何 Markdown
- 长文档用它隐藏次要细节
- FAQ 列表常用
</details>
适合：FAQ、长示例、调试细节。
这是FAQ、调试日志、长示例的救星。原生 HTML 标签，所有 Markdown 引擎都支持。
11. 兼容性提示
本章讲的高级语法不是 CommonMark 标准，跨引擎兼容性如下：
- 警告框：GitHub、GitLab 较新版本、VitePress、Obsidian（语法略不同）。
- 脚注：GitHub、Pandoc、Obsidian、VitePress；少数老引擎不支持。
- Mermaid：GitHub、GitLab、Notion、Obsidian、VitePress。
- 数学公式：GitHub、Pandoc、Obsidian、VitePress。
- 任务列表：GFM 标准，所有 GFM 引擎都支持。
发布前先确认目标平台支持。如果不支持，可以用 HTML 或图片替代。
12. 选择扩展的取舍
- 面向 GitHub：放心用所有 GFM 语法，渲染效果最佳。
- 面向博客（Hexo/Hugo）：看主题和插件，多数都支持扩展。
- 面向通用发布：保守一点，只用 CommonMark + GFM 基础语法。
- 面向打印 / PDF：脚注、表格、图片友好；Mermaid 可能渲染不出。
小结
恭喜！你已学完 Markdown 系列 9 篇全部内容。从最简单的标题、段落，到 Mermaid 流程图、数学公式——这套语法足以覆盖你 99% 的写作场景。下一步：在自己的 README、博客、笔记里实际用起来，遇到问题再回查本系列。
← 上一篇 引用
← 返回 Markdown 教程目录