Markdown: GFM 扩展语法与 Emoji
Markdown 有标准版和扩展版之分——GitHub Flavored Markdown 是使用最广泛的扩展，增加了很多实用的语法功能。
1. 你将学到
- GFM 与标准 Markdown 的区别
- 任务列表的完整用法
- Emoji 表情的插入方式
- 脚注和定义列表的使用
- 自动链接与 URL 识别
- 忽略 Markdown 语法的方法
2. 一个开源维护者的真实故事
(1) 痛点：Issue 中缺少结构化信息
Morgan 维护着一个有 5000+ Star 的开源项目，每天收到几十个 Issue。用户提交的问题散乱无章——有的没有步骤、有的忘记贴错误信息、有的在标题里加了 emoji 导致过滤困难。维护者需要花大量时间追问"你用的什么版本"、"完整的错误信息是什么"。
(2) 解法：用 GFM 创建 Issue 模板
Morgan 创建了 GitHub Issue 模板，使用任务列表（- [ ] 检查清单）、表格（版本/环境信息）、代码块（错误日志）来结构化信息。emoji 用于标记 Issue 类型：🐛 Bug、✨ Feature、📖 Documentation。模板上线后，Issues 的信息完整率从 30% 提升到 85%，平均处理时间缩短了一半。
3. GFM 概述
GitHub Flavored Markdown（GFM）是标准 Markdown 的超集，在 CommonMark 规范基础上增加了 GitHub 特定的扩展：
graph TB
A[GFM - GitHub Flavored Markdown] --> B[CommonMark 标准]
A --> C[GFM 扩展]
C --> D[任务列表]
C --> E[表格]
C --> F[删除线]
C --> G[自动链接]
C --> H[Emoji]
C --> I[忽略语法]
| 功能 | 标准 Markdown | GFM |
|---|---|---|
| 表格 | ❌ 无标准 | ✅ 支持完整 |
| 任务列表 | ❌ 无标准 | ✅ 支持 |
| 删除线 | ❌ 无标准 | ✅ |
| 自动链接 | ⚠️ 仅 <> |
✅ URL 自动识别 |
| Emoji | ❌ 无标准 | ✅ :smile: |
| 代码块内语法高亮 | ⚠️ 部分支持 | ✅ 完整支持 |
| 忽略 Markdown | ❌ 不支持 | ✅ \ 转义 |
4. Emoji 表情
(1) 两种插入方式
方式一（推荐）：用冒号包围的短代码
:smile: → 😄
:rocket: → 🚀
:warning: → ⚠️
方式二：直接复制粘贴 emoji 字符
😄 🚀 ⚠️ ✅ ❌
(2) 常用技术文档 emoji
✅ 完成 / ❌ 失败 / ⚠️ 注意
🐛 Bug / ✨ 新功能 / 📖 文档
🚀 发布 / 🔧 配置 / 🎨 样式
📦 依赖 / 🔒 安全 / 📊 数据
:smile:）。有些平台只支持直接粘贴 emoji 字符。建议在非 GitHub 场景直接粘贴 emoji 字符以获得最大兼容性。
▶ 示例：用 emoji 标注 Issue 类型
## Issue 模板
### 类型
- 🐛 Bug 报告
- ✨ 功能请求
- 📖 文档改进
- 🔧 配置问题
### 环境
- 操作系统：macOS 14.5
- 浏览器：Chrome 126
- 版本：v2.3.1
5. 自动链接与 URL 识别
(1) URL 自动识别
GFM 自动将 URL 转换为可点击的链接，无需 <>：
访问 https://github.com 了解更多。
文档地址：https://developer.mozilla.org
项目仓库：https://github.com/user/repo
(2) 邮箱自动识别
联系我们：support@example.com
作者邮箱：author@example.com
6. 忽略 Markdown 语法
用 \ 反斜杠转义，让 Markdown 符号显示为普通文字：
\# 这不是标题，而是显示 "#" 字符
\*\*这不是加粗\*\*
\- 这不是列表项
\[这不是链接\](url)
` 包裹符号来显示其原始形态：`#` 显示为 # 而不是标题。
▶ 示例：常见转义场景
在写教程时，有时需要显示 Markdown 语法本身：
用 \`#\` 表示一级标题。
语法示例：\*\*加粗文字\*\*
在代码中是 `**实际加粗**`（这里用反引号包裹，不会加粗）。
`**文字**` 会显示为代码样式，且不会渲染为加粗。
7. 其他 GFM 扩展
(1) 删除线
~~这行文字被删除了~~
~~这个功能已废弃~~
(2) 表格中支持更多格式
GFM 表格支持代码、链接、多项内容：
| 命令 | 描述 | 示例 |
|:-----|:-----|:------|
| `git status` | 查看状态 | [文档][status] |
| `git log` | 查看历史 | `--oneline` 简约模式 |
| ~~`git merge`~~ | 已弃用 | 改用 `rebase` |
[status]: https://git-scm.com/docs/git-status
(3) 代码块内的语法高亮
GFM 支持数十种语言的语法高亮：
name: CI Pipeline
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: npm test
diff 语言标签，+ 行显示为绿色（新增），- 行显示为红色（删除），非常适合展示代码变更。
▶ 示例：用 diff 展示代码修改
# 旧版
- <script src="old-script.js"></script>
# 新版
+ <script src="new-script.min.js" defer></script>
8. 完整示例：用 GFM 写一篇完整 Issue
Issue 标题：在 Firefox 中导航栏无法展开
环境：
操作系统 | Windows 11
浏览器 | Firefox 128.0
版本 | v3.2.1
复现步骤：
1. 打开应用
2. 点击右上角用户菜单
3. 菜单无法展开
日志内容：
[2026-06-15 14:32:01] User clicked nav-toggle
[2026-06-15 14:32:03] No response from toggle handler
预期效果：一个结构化的 GitHub Issue，类型标注清晰（Bug），环境信息用表格，复现步骤用有序列表，检查清单用任务列表。
预期效果：一个结构化的 GitHub Issue，类型标注清晰（🐛 Bug），环境信息用表格，复现步骤用有序列表，检查清单用任务列表。
❓ 常见问题
:smile:）在任何地方都能用吗？:smile: 仅在 GitHub、GitLab、Slack 等特定平台有效。在 VS Code 和 Typora 中，推荐直接粘贴 emoji 字符。--from gfm，marked.js 默认支持 GFM，Python-Markdown 需要 extensions=['extra']。[TOC] 是 GFM 的一部分吗？[TOC] 是某些编辑器（如 VS Code 的 Markdown All in One 扩展、Typora）的自定义功能，不是任何 Markdown 标准的一部分。📖 小节
- GFM 是 GitHub 基于 CommonMark 的扩展，增加了任务列表、表格、删除线等
- Emoji 可用
:code:（GitHub 平台）或直接粘贴字符 - GFM 自动识别 URL 和邮箱，无需
<> - 用
\转义 Markdown 特殊字符，显示原始符号 diff语言标签用+/-展示代码变更[TOC]等不是标准或 GFM 的一部分，属于编辑器自定义
📝 作业
-
基础题：写一份 Git 项目提交信息规范文档，包含使用 emoji 标记提交类型（如
✨ 新功能🐛 修复），并用任务列表作为提交前检查清单。 -
进阶题：用
diff语言标签展示一段代码的变更前后对比（至少 5 行，包含新增和删除行）。然后用自动链接功能引用一个 GitHub 仓库。 -
挑战题：创建一个完整的 GitHub Issue 模板，综合使用表格（环境信息）、任务列表（检查清单）、有序列表（复现步骤）、代码块（日志/配置）、emoji（类型标记）和引用（截图/额外说明）。
