第 6 章：GFM 扩展语法精讲
GitHub Flavored Markdown (GFM) 是 GitHub 在标准 Markdown 基础上开发的扩展版本，增加了许多实用的功能。这些扩展不仅让文档更加生动有趣，还提供了更强大的表达能力。本章将深入探讨 GFM 的独有特性，帮助你充分利用这些强大的功能。
什么是 GitHub Flavored Markdown？
GitHub Flavored Markdown (GFM) 是 GitHub 基于 CommonMark 规范开发的 Markdown 方言。它在保持标准 Markdown 语法的同时，添加了许多实用的扩展功能，使其更适合在 GitHub 平台上进行协作和文档编写。
因此，你项目
README.md在 Github 的渲染效果，并不能保证在其它的渲染器中能有相同或者类似的效果；
要知道，不同的渲染器/写作软件渲染效果是有差异的。
GFM 的主要优势
- 更丰富的表达方式：支持删除线、表情符号等
- 更好的协作体验：支持 @提及、自动链接等
- 更强的兼容性：被众多平台和工具支持
- 持续更新：GitHub 持续改进和扩展功能
GFM 的应用场景
- GitHub 仓库：README、Issues、Pull Requests
- 技术博客：许多静态网站生成器支持 GFM
- 文档平台：GitBook、Notion、语雀等
- 协作工具：Slack、Discord、Teams 等
6.1 删除线：标记过时或错误的内容
删除线用于标记已经过时、被删除或错误的内容，在版本控制、文档更新和协作中非常有用。
基本语法
使用两个波浪号 ~~ 包裹需要添加删除线的文本：
这是正常文本，~~这是被删除的文本~~，这又是正常文本。
渲染效果：
这是正常文本，这是被删除的文本，这又是正常文本。
实际应用场景
1. 标记已废弃的功能
## API 接口列表
- `GET /api/users` - 获取用户列表
- `POST /api/users` - 创建新用户
- ~~`PUT /api/users/:id`~~ - 更新用户信息（已废弃，请使用 PATCH）
- `PATCH /api/users/:id` - 更新用户信息
- `DELETE /api/users/:id` - 删除用户
渲染效果：
API 接口列表
GET /api/users- 获取用户列表POST /api/users- 创建新用户PUT /api/users/:idPATCH /api/users/:id- 更新用户信息DELETE /api/users/:id- 删除用户
2. 显示价格变更
## 产品价格
| 产品名称 | 原价 | 现价 |
|----------|------|------|
| iPhone 15 | ~~¥6,999~~ | ¥5,999 |
| MacBook Air | ~~¥8,999~~ | ¥7,999 |
| iPad Pro | ¥6,999 | ¥6,999 |
渲染效果：
| 产品名称 | 原价 | 现价 |
|---|---|---|
| iPhone 15 | ¥5,999 | |
| MacBook Air | ¥7,999 | |
| iPad Pro | ¥6,999 | ¥6,999 |
3. 任务列表中的完成项
## 项目开发进度
- [x] ~~设计数据库结构~~ ✅ 已完成
- [x] ~~实现用户认证~~ ✅ 已完成
- [ ] 开发核心功能
- [ ] 编写测试用例
- [ ] 部署到生产环境
渲染效果：
-
设计数据库结构✅ 已完成 -
实现用户认证✅ 已完成 - 开发核心功能
- 编写测试用例
- 部署到生产环境
4. 文档版本更新
## 更新日志
### v2.1.0 (2024-01-15)
- 新增用户权限管理功能
- 优化数据库查询性能
- ~~修复登录页面样式问题~~ (已在 v2.0.1 修复)
- 更新 API 文档
### v2.0.1 (2024-01-10)
- 修复登录页面样式问题
- ~~临时禁用邮件通知功能~~ (已在 v2.1.0 重新启用)
删除线的最佳实践
1. 提供替代方案
# ✅ 好的做法：提供替代信息
~~旧的配置方法：使用 config.xml~~
**新的配置方法**：请使用 `config.json` 文件进行配置。
# ❌ 不好的做法：只删除不说明
~~使用 config.xml~~
2. 保留重要的历史信息
# ✅ 保留上下文
## 安装方法
**当前推荐方法**：
```bash
npm install @latest/package
历史方法（仅供参考）：
npm install old-package
❌ 完全删除历史信息
安装方法
npm install @latest/package
**3. 与其他格式结合使用**
```markdown
- **重要更新**：~~原 API 端点~~ → 新 API 端点
- **注意**：~~旧功能~~ 将在下个版本中移除
- **提醒**：请将 ~~`oldFunction()`~~ 替换为 `newFunction()`
6.2 表情符号：让文档更生动有趣
表情符号（Emoji）可以让文档更加生动有趣，提升阅读体验，在技术文档中也能起到很好的视觉引导作用。
基本语法
GFM 支持使用 :emoji_code: 的格式插入表情符号：
我今天很开心 :smile:！
这个功能很棒 :thumbsup:！
注意安全 :warning:！
渲染效果：
我今天很开心 😄！
这个功能很棒 👍！
注意安全 ⚠️！
常用表情符号分类
1. 情感表达
| 代码 | 表情 | 含义 |
|---|---|---|
:smile: | 😄 | 开心、高兴 |
:laughing: | 😆 | 大笑 |
:heart_eyes: | 😍 | 喜爱 |
:thinking: | 🤔 | 思考 |
:confused: | 😕 | 困惑 |
:cry: | 😢 | 哭泣 |
:rage: | 😡 | 愤怒 |
:sleeping: | 😴 | 睡觉 |
2. 手势动作
| 代码 | 表情 | 含义 |
|---|---|---|
:thumbsup: | 👍 | 赞同、好 |
:thumbsdown: | 👎 | 反对、不好 |
:clap: | 👏 | 鼓掌 |
:wave: | 👋 | 挥手 |
:point_right: | 👉 | 指向右边 |
:point_left: | 👈 | 指向左边 |
:point_up: | 👆 | 指向上方 |
:point_down: | 👇 | 指向下方 |
3. 状态指示
| 代码 | 表情 | 含义 |
|---|---|---|
:white_check_mark: | ✅ | 完成、正确 |
:x: | ❌ | 错误、失败 |
:warning: | ⚠️ | 警告 |
:information_source: | ℹ️ | 信息 |
:question: | ❓ | 疑问 |
:exclamation: | ❗ | 感叹、重要 |
:heavy_check_mark: | ✔️ | 检查、确认 |
:heavy_multiplication_x: | ✖️ | 删除、取消 |
4. 技术相关
| 代码 | 表情 | 含义 |
|---|---|---|
:computer: | 💻 | 计算机 |
:iphone: | 📱 | 手机 |
:gear: | ⚙️ | 设置、配置 |
:wrench: | 🔧 | 工具、修复 |
:hammer: | 🔨 | 构建、开发 |
:bug: | 🐛 | Bug、错误 |
:rocket: | 🚀 | 发布、部署 |
:fire: | 🔥 | 热门、重要 |
5. 文档结构
| 代码 | 表情 | 含义 |
|---|---|---|
:book: | 📖 | 文档、教程 |
:memo: | 📝 | 笔记、记录 |
:page_facing_up: | 📄 | 页面、文件 |
:clipboard: | 📋 | 清单、列表 |
:chart_with_upwards_trend: | 📈 | 增长、统计 |
:bulb: | 💡 | 想法、提示 |
:lock: | 🔒 | 安全、私有 |
:key: | 🔑 | 密钥、权限 |
实际应用示例
1. 项目 README 文档
# 🚀 我的项目
一个令人兴奋的新项目！
## ✨ 特性
- 🎯 高性能
- 🛡️ 安全可靠
- 📱 响应式设计
- 🌍 国际化支持
## 🚀 快速开始
### 📋 前置要求
- Node.js 16+ 💻
- npm 或 yarn 📦
### ⚡ 安装
```bash
npm install
🏃♂️ 运行
npm start
📖 文档
详细文档请查看 Wiki 📚
🤝 贡献
欢迎提交 Issue 和 Pull Request！
📄 许可证
MIT License
**2. 状态报告**
```markdown
## 📊 项目状态报告
### ✅ 已完成
- 🏗️ 项目架构设计
- 🎨 UI/UX 设计
- 💾 数据库设计
- 🔐 用户认证系统
### 🚧 进行中
- 📱 移动端适配 (80% 完成)
- 🧪 单元测试编写 (60% 完成)
- 📝 API 文档编写 (40% 完成)
### ⏳ 待开始
- 🚀 性能优化
- 🌐 国际化
- 📈 数据分析
### ⚠️ 风险提醒
- 🐛 已知 Bug：登录页面在 IE 浏览器下显示异常
- ⏰ 时间风险：测试阶段可能需要额外 1 周时间
- 💰 预算风险：第三方服务费用可能超出预期
3. 技术文档
# 🔧 API 使用指南
## 🚀 快速开始
### 🔑 获取 API Key
1. 访问 [开发者控制台](https://console.example.com) 🌐
2. 创建新应用 ➕
3. 复制 API Key 📋
### 📡 发送请求
```javascript
const response = await fetch('https://api.example.com/users', {
headers: {
'Authorization': `Bearer ${apiKey}`,
'Content-Type': 'application/json'
}
});
📚 API 参考
👤 用户管理
| 方法 | 端点 | 描述 | 状态 |
|---|---|---|---|
| GET | /users | 获取用户列表 | ✅ 稳定 |
| POST | /users | 创建用户 | ✅ 稳定 |
| PUT | /users/:id | 更新用户 | ⚠️ 即将废弃 |
| DELETE | /users/:id | 删除用户 | ❌ 维护中 |
📊 响应状态码
- 200 ✅ 成功
- 400 ❌ 请求错误
- 401 🔒 未授权
- 404 🔍 未找到
- 500 💥 服务器错误
### 表情符号的最佳实践
**1. 适度使用**
```markdown
# ✅ 适度使用：突出重点
## 🚀 快速开始
按照以下步骤开始使用：
1. 安装依赖
2. 配置环境
3. 启动服务
# ❌ 过度使用：影响阅读
## 🚀 快速开始 🎯
按照以下步骤开始使用 💻：
1. 安装依赖 📦
2. 配置环境 ⚙️
3. 启动服务 🏃♂️
2. 保持一致性
# ✅ 一致的使用模式
## ✅ 已完成的功能
## 🚧 开发中的功能
## ⏳ 计划中的功能
# ❌ 不一致的使用
## ✅ 已完成的功能
## 正在开发的功能 🚧
## ⏳ 计划功能
3. 考虑受众
# ✅ 技术文档：专业简洁
## 🔧 配置说明
## ⚠️ 注意事项
## 📖 参考文档
# ✅ 社区项目：友好活泼
## 🎉 欢迎贡献！
## 💖 感谢支持
## 🌟 给个 Star 吧！
表情符号查询资源
- GitHub Emoji API：api.github.com/emojis
- Emoji Cheat Sheet：github.com/ikatyang/em…
- Emojipedia：emojipedia.org/
- Unicode Emoji Charts：unicode.org/emoji/chart…
6.3 自动链接：智能识别 URL 和邮箱
GFM 的自动链接功能可以智能识别文本中的 URL 和邮箱地址，自动将它们转换为可点击的链接，无需手动添加链接语法。
URL 自动链接
基本功能
访问我们的网站：https://www.example.com
查看项目仓库：https://github.com/username/repository
在线演示：http://demo.example.com
渲染效果：
访问我们的网站：www.example.com
查看项目仓库：github.com/username/re…
在线演示：demo.example.com
支持的协议
- HTTP：http://example.com
- HTTPS：https://example.com
- FTP：ftp://files.example.com
- 文件协议：file:///path/to/file
渲染效果：
- HTTP：example.com
- HTTPS：example.com
- FTP：ftp://files.example.com
- 文件协议：file:///path/to/file
邮箱自动链接
联系我们：contact@example.com
技术支持：support@company.org
商务合作：business@startup.io
渲染效果：
联系我们：contact@example.com
技术支持：support@company.org
商务合作：business@startup.io
实际应用场景
1. 项目文档中的链接
# 项目资源
## 相关链接
- 项目主页：https://myproject.com
- 文档站点：https://docs.myproject.com
- 问题反馈：https://github.com/user/project/issues
- 在线演示：https://demo.myproject.com
## 联系方式
- 项目维护者：maintainer@myproject.com
- 技术支持：support@myproject.com
- 商务合作：business@myproject.com
2. 团队信息
# 团队成员
| 姓名 | 角色 | 邮箱 | GitHub |
|------|------|------|--------|
| 张三 | 项目经理 | zhangsan@company.com | https://github.com/zhangsan |
| 李四 | 前端开发 | lisi@company.com | https://github.com/lisi |
| 王五 | 后端开发 | wangwu@company.com | https://github.com/wangwu |
3. 资源列表
# 学习资源
## 官方文档
- React 官方文档：https://reactjs.org/docs
- Vue.js 官方文档：https://vuejs.org/guide
- Angular 官方文档：https://angular.io/docs
## 在线工具
- CodePen：https://codepen.io
- JSFiddle：https://jsfiddle.net
- StackBlitz：https://stackblitz.com
## 社区资源
- Stack Overflow：https://stackoverflow.com
- Reddit 前端社区：https://reddit.com/r/Frontend
- 掘金：https://juejin.cn
自动链接的限制和注意事项
1. 标点符号处理
# ✅ 正确识别
访问网站：https://example.com。
查看文档：https://docs.example.com！
# ⚠️ 可能的问题
链接在括号中：(https://example.com)
链接后有逗号：https://example.com, 还有其他内容
2. 复杂 URL 的处理
# ✅ 简单 URL 自动识别
https://example.com/path
# ⚠️ 复杂 URL 建议手动添加链接
[搜索结果](https://google.com/search?q=markdown&hl=zh-CN)
[带锚点的链接](https://example.com/docs#section-1)
3. 与其他语法的冲突
# ✅ 在代码块中不会自动转换
配置文件中的 URL：api.example.com
# ✅ 在行内代码中不会自动转换
配置 API 端点为 `https://api.example.com`
最佳实践
1. 明确链接用途
# ✅ 提供上下文
查看完整的 API 文档：https://docs.example.com/api
# ❌ 缺少上下文
https://docs.example.com/api
2. 重要链接使用手动语法
# ✅ 重要链接提供描述性文本
[下载最新版本](https://github.com/user/project/releases/latest)
# ⚠️ 自动链接缺少描述
https://github.com/user/project/releases/latest
3. 邮箱链接的隐私考虑
# ✅ 公开邮箱可以直接使用
联系我们：support@company.com
# ✅ 私人邮箱考虑隐私保护
联系方式：john[at]example[dot]com
6.4 提及功能：GitHub 协作的利器
@提及（@mentions）是 GFM 在 GitHub 平台上的特色功能，允许你在 Issues、Pull Requests、评论等地方提及其他用户或团队，实现高效的协作沟通。
基本语法
@username - 提及用户
@organization/team - 提及组织中的团队
用户提及
提及单个用户
@zhangsan 请帮忙 review 这个 PR。
@lisi 这个 bug 你能看一下吗？
感谢 @wangwu 的贡献！
提及多个用户
@zhangsan @lisi @wangwu 请大家参与讨论这个新功能的设计。
团队提及
@myorg/frontend-team 请 review 前端相关的代码。
@myorg/backend-team 后端 API 有更新，请注意。
@myorg/devops-team 需要帮助部署新版本。
实际应用场景
1. Issue 讨论
# Bug 报告：登录页面样式问题
## 问题描述
在 Chrome 浏览器中，登录页面的按钮样式显示异常。
## 重现步骤
1. 打开登录页面
2. 查看登录按钮
3. 发现样式错误
## 期望行为
按钮应该显示为蓝色背景，白色文字。
---
@frontend-team 这个问题可能与最近的 CSS 更新有关，请帮忙查看一下。
@zhangsan 作为前端负责人，请分配给合适的开发者处理。
2. Pull Request 审查
# 添加用户权限管理功能
## 变更说明
- 新增用户角色管理
- 实现权限检查中间件
- 更新相关测试用例
## 测试
- [x] 单元测试通过
- [x] 集成测试通过
- [ ] 手动测试待完成
---
@backend-team 请 review 后端代码变更。
@lisi 请特别关注权限检查的逻辑是否正确。
@test-team 请帮忙进行完整的功能测试。
3. 项目管理
# 项目进度更新 - 2024年1月
## 已完成
- ✅ 用户认证系统 (@zhangsan)
- ✅ 数据库设计 (@lisi)
- ✅ API 接口开发 (@wangwu)
## 进行中
- 🚧 前端界面开发 (@frontend-team)
- 🚧 测试用例编写 (@test-team)
## 下周计划
- 📋 完成前端开发 (@frontend-team)
- 📋 开始集成测试 (@test-team)
- 📋 准备部署环境 (@devops-team)
---
@all-team 请大家按计划推进各自的任务，有问题及时沟通。
@project-manager 请关注整体进度，确保按时交付。
4. 代码审查评论
## 代码审查意见
### 第 45 行
```javascript
if (user.role === 'admin') {
// 管理员逻辑
}
```
建议使用常量而不是硬编码字符串：
```javascript
if (user.role === USER_ROLES.ADMIN) {
// 管理员逻辑
}
```
@zhangsan 请修改这个地方。
### 第 78 行
缺少错误处理，建议添加 try-catch。
@lisi 你觉得这里的错误处理应该怎么做？
提及功能的特点
1. 实时通知
当你被提及时，会收到：
- GitHub 网站通知
- 邮件通知（如果启用）
- 移动应用推送（如果安装）
2. 权限控制
- 只有仓库的协作者才能被提及
- 私有仓库的提及不会发送给外部用户
- 可以在设置中控制通知偏好
3. 自动完成
在 GitHub 界面中输入 @ 时会显示：
- 仓库协作者列表
- 组织团队列表
- 最近互动的用户
最佳实践
1. 明确提及目的
# ✅ 明确说明需要什么
@zhangsan 请帮忙 review 这个 PR 中的安全相关代码。
# ❌ 提及但不说明目的
@zhangsan 看一下这个。
2. 避免过度提及
# ✅ 只提及相关人员
@frontend-team 前端代码有更新。
# ❌ 提及不相关的人
@frontend-team @backend-team @devops-team @test-team 前端代码有更新。
3. 使用团队提及提高效率
# ✅ 使用团队提及
@security-team 请审查这个安全补丁。
# ❌ 逐个提及团队成员
@alice @bob @charlie @david 请审查这个安全补丁。
4. 在合适的时机提及
# ✅ 在需要输入时提及
实现完成，@reviewer 请 review。
# ❌ 在讨论初期就提及
我在考虑实现这个功能，@everyone 你们觉得呢？
提及功能的局限性
1. 平台限制
- 主要在 GitHub 平台有效
- 其他平台可能不支持或有不同实现
- 导出的文档中提及会变成普通文本
2. 隐私考虑
- 公开仓库中的提及对所有人可见
- 注意不要在提及中泄露敏感信息
- 考虑用户的通知偏好
3. 滥用风险
- 过度提及可能被视为垃圾信息
- 可能导致用户关闭通知
- 影响团队协作效率
本章小结
在这一章中，我们深入学习了 GitHub Flavored Markdown 的扩展语法：
主要内容回顾
-
删除线：
- 语法：
~~text~~ - 用途：标记过时、错误或已删除的内容
- 最佳实践：提供替代方案，保留历史信息
- 语法：
-
表情符号：
- 语法：
:emoji_code: - 分类：情感、手势、状态、技术、文档
- 最佳实践：适度使用，保持一致性
- 语法：
-
自动链接：
- 功能：自动识别 URL 和邮箱
- 支持：HTTP/HTTPS/FTP 等协议
- 注意：复杂 URL 建议手动添加
-
提及功能：
- 语法：
@username、@org/team - 用途：GitHub 协作和通知
- 最佳实践：明确目的，避免滥用
- 语法：
GFM 的价值
- 增强表达力：让文档更生动有趣
- 提升协作效率：特别是在 GitHub 平台
- 改善用户体验：更直观的视觉效果
- 标准化沟通：统一的协作语言
下一步学习
在下一章中，我们将探讨 Markdown 编辑器和插件的选择，学习如何构建高效的写作工作流，让你的 Markdown 写作体验更上一层楼。
练习建议：尝试在你的 GitHub 项目中使用这些 GFM 扩展语法，特别是在 README 文件和 Issues 中，体验它们带来的便利和表达力的提升。
