GitHub Flavored Markdown (GFM)
GitHub Flavored Markdown (GFM) 是 GitHub 的增强版 Markdown，具有专为软件开发和协作设计的额外功能。本指南涵盖 GitHub 上所有可用的特殊语法扩展。
什么是 GitHub Flavored Markdown (GFM)？
GitHub Flavored Markdown 在基础 Markdown 语法上扩展了以下功能，使其更适用于：
- 文档（README、维基）
- 问题跟踪
- 拉取请求
- 代码审查
- 项目管理
GFM 核心功能
1. 围栏代码块
GFM 支持带有语言特定语法高亮的围栏代码块：
```javascript
function calculateSum(numbers) {
return numbers.reduce((sum, num) => sum + num, 0);
}
const result = calculateSum([1, 2, 3, 4, 5]);
console.log(result); // 输出：15
```javascript
function calculateSum(numbers) {
return numbers.reduce((sum, num) => sum + num, 0);
}
const result = calculateSum([1, 2, 3, 4, 5]);
console.log(result); // 输出：152. 语法高亮
GitHub 支持数百种语言的语法高亮。以下是一些常见的语言：
bash
# Bash 脚本
echo "Hello GitHub!"python
# Python 脚本
def greet(name):
return f"Hello, {name}!"java
// Java 代码
public class HelloWorld {
public static void main(String[] args) {
System.out.println("Hello GitHub!");
}
}3. 任务列表
使用复选框创建交互式任务列表：
markdown
- [x] 完成用户认证
- [x] 实现 API 端点
- [ ] 编写单元测试
- [ ] 后端测试
- [ ] 前端测试
- [ ] 部署到生产环境- [x] 完成用户认证
- [x] 实现 API 端点
- [ ] 编写单元测试
- [ ] 后端测试
- [ ] 前端测试
- [ ] 部署到生产环境
4. 表格
GFM 提供简单的表格创建语法：
markdown
| 功能 | 支持 | 描述 |
|-----------------|------|-------------------------------|
| 围栏代码 | ✅ | 语言特定高亮 |
| 任务列表 | ✅ | 交互式复选框 |
| 表格 | ✅ | 结构化数据显示 |
| 提及 | ✅ | 用户和团队通知 |
| 表情符号 | ✅ | 视觉表达 || 功能 | 支持 | 描述 |
|---|---|---|
| 围栏代码 | ✅ | 语言特定高亮 |
| 任务列表 | ✅ | 交互式复选框 |
| 表格 | ✅ | 结构化数据显示 |
| 提及 | ✅ | 用户和团队通知 |
| 表情符号 | ✅ | 视觉表达 |
5. 提及
提及用户或团队以通知他们：
markdown
@username - 提及特定用户
@team-name - 提及团队6. 表情符号
使用短代码添加表情符号：
markdown
:smile: - 😊
:thumbsup: - 👍
:heart: - ❤️
:rocket: - 🚀
:warning: - ⚠️😄 - 😊 👍 - 👍 ❤️ - ❤️ 🚀 - 🚀 ⚠️ - ⚠️
7. 自动链接
GFM 自动链接某些类型的内容：
问题和拉取请求编号
markdown
#123 - 链接到问题 123
PR #456 - 链接到拉取请求 456SHA 哈希
markdown
a1b2c3d - 链接到此 SHA 的提交问题/拉取请求中的用户提及
markdown
@username - 自动链接到用户个人资料URL
markdown
https://github.com - 自动变成链接8. 删除线
GFM 支持删除线文本：
markdown
~~这段文字被划掉了~~这段文字被划掉了
9. 自动链接引用
GFM 自动为以下内容创建链接：
- HTTP/HTTPS URL
- 电子邮件地址
- GitHub 问题/拉取请求编号
- 提交 SHA
markdown
https://github.com/markdownlang/markdownlang.com
user@example.com
#123
PR #456
a1b2c3d4e5f610. 代码块行高亮
高亮显示代码块中的特定行：
```javascript{2,4}
function calculateSum(numbers) {
return numbers.reduce((sum, num) => sum + num, 0); // 高亮
}
const result = calculateSum([1, 2, 3, 4, 5]); // 高亮
console.log(result);
```javascript
function calculateSum(numbers) {
return numbers.reduce((sum, num) => sum + num, 0); // 高亮
}
11. Diff 语法高亮
使用 diff 语法高亮显示代码变更：
```diff
- const oldFunction = () => {
- return "old value";
- };
+
+ const newFunction = () => {
+ return "new value";
+ };
```diff
- const oldFunction = () => {
- return "old value";
- };
+
+ const newFunction = () => {
+ return "new value";
+ };12. GitHub 特定标记
警告框
在 GitHub 文档中使用特殊语法创建警告框：
markdown
> [!NOTE]
> 这是一个注意警告框。
> [!TIP]
> 这是一个提示警告框。
> [!IMPORTANT]
> 这是一个重要警告框。
> [!WARNING]
> 这是一个警告警告框。
> [!CAUTION]
> 这是一个 caution 警告框。NOTE
这是一个注意警告框。
TIP
这是一个提示警告框。
IMPORTANT
这是一个重要警告框。
WARNING
这是一个警告警告框。
CAUTION
这是一个 caution 警告框。
相对链接
使用相对链接在同一仓库中的文件之间导航：
markdown
[README](/README.md)
[贡献指南](/CONTRIBUTING.md)
[API 文档](/docs/api.md)带悬停文本的图片链接
markdown
GFM 高级用法
1. 嵌套列表与任务列表
将嵌套列表与任务列表结合：
markdown
## 项目路线图
### 第一阶段：规划
- [x] 定义项目范围
- [x] 识别需求
- [x] 功能需求
- [x] 非功能需求
- [x] 创建时间表
### 第二阶段：开发
- [x] 设置项目结构
- [ ] 实现核心功能
- [x] 认证
- [ ] 仪表板
- [ ] API 集成2. 带表情符号和链接的表格
使用表情符号和链接增强表格：
markdown
| 组件 | 状态 | 维护者 |
|------|------|--------|
| 认证 | ✅ 稳定 | @johndoe |
| 数据库 | ⚠️ 需要更新 | @janedoe |
| API | 🚧 进行中 | @bobsmith |
| UI | ✅ 稳定 | @alicesmith || 组件 | 状态 | 维护者 |
|---|---|---|
| 认证 | ✅ 稳定 | @johndoe |
| 数据库 | ⚠️ 需要更新 | @janedoe |
| API | 🚧 进行中 | @bobsmith |
| UI | ✅ 稳定 | @alicesmith |
3. 列表中的代码块
在列表中包含代码块：
markdown
1. 安装依赖：
```bash
npm install运行开发服务器：
bashnpm run dev构建生产版本：
bashnpm run build
### 4. 带代码的引用块
将引用块与代码块结合：
```markdown
> **专业提示：** 使用以下命令快速检查 Git 状态：
>
> ```bash
> git status
> ```专业提示： 使用以下命令快速检查 Git 状态：
bashgit status
GFM 在不同 GitHub 场景中的应用
README 文件
README 文件支持所有 GFM 功能，并在仓库页面上自动渲染。
问题和拉取请求
- 使用任务列表跟踪进度
- 提及团队成员进行协作
- 包含带语法高亮的代码片段
- 使用
#123语法引用相关问题/拉取请求
评论
- 使用表情符号进行快速反应
- 使用行评论引用代码中的特定行
- 使用引用块回应特定点
维基
- 使用嵌套页面组织内容
- 使用表格显示结构化数据
- 包含带语法高亮的代码示例
最佳实践
1. 代码风格
markdown
<!-- ✅ 好的 -->
```javascript
// 使用描述性的函数名
function calculateTotal(items) {
return items.reduce((sum, item) => sum + item.price, 0);
}javascript
function f(i){return i.reduce((a,b)=>a+b.p,0)}```2. 表格设计
markdown
<!-- ✅ 好的 -->
| 功能 | 描述 | 状态 |
|------|------|------|
| 功能 1 | 简短描述 | ✅ |
| 功能 2 | 另一个描述 | 🚧 |
<!-- ❌ 避免 -->
| 功能 | 描述 | 状态 | | | |
|------|------|------|---|---|---|
| 功能 1 | 这个描述太长了，在移动设备上难以阅读 | ✅ | | | |3. 任务列表使用
markdown
<!-- ✅ 好的 -->
## 冲刺待办事项
- [x] 完成用户个人资料页面
- [ ] 实现搜索功能
- [x] 后端 API
- [ ] 前端组件
- [ ] 编写文档
<!-- ❌ 避免 -->
- [ ] 任务 1
- [ ] 任务 2
- [ ] 任务 3
- [ ] 任务 4
- [ ] 任务 5
（太多任务没有组织）GFM 与标准 Markdown 对比
| 功能 | 标准 Markdown | GitHub Flavored Markdown |
|---|---|---|
| 围栏代码块 | ❌ | ✅ |
| 语法高亮 | ❌ | ✅ |
| 任务列表 | ❌ | ✅ |
| 表格 | ❌ | ✅ |
| 删除线 | ❌ | ✅ |
| 表情符号 | ❌ | ✅ |
| 提及 | ❌ | ✅ |
| 自动链接 | 有限 | 广泛 |
GFM 工具
本地编辑器
- Visual Studio Code - GFM 预览和扩展
- Typora - 实时 GFM 渲染
- Mark Text - GFM 支持
在线工具
- GitHub Gist - 创建和分享 GFM 片段
- Dillinger - 在线 GFM 编辑器
- StackEdit - 支持云同步的 GFM 编辑器
命令行工具
- glow - 终端 GFM 渲染器
- pandoc - 将 GFM 转换为其他格式
- marked - Node.js GFM 解析器
常见问题和修复
1. 代码块没有高亮
问题： 代码块没有显示语法高亮
修复： 确保指定了正确的语言：
markdown
<!-- ✅ 正确 -->
```javascript
console.log("Hello");jsx
console.log("Hello"); // 对非 JSX 代码使用 jsx 而不是 javascript
### 2. 任务列表复选框不工作
**问题：** 任务列表复选框没有交互性
**修复：** 确保使用正确的语法（`-` 和 `[ ]` 之间有空格）：
```markdown
<!-- ✅ 正确 -->
- [ ] 任务
<!-- ❌ 不正确 -->
-[ ] 任务（没有空格）
-[x] 任务（没有空格）3. 表格渲染不正确
问题： 表格列未对齐
修复： 确保管道符正确对齐：
markdown
<!-- ✅ 正确 -->
| 列 1 | 列 2 |
|------|------|
| 数据 1 | 数据 2 |
<!-- ❌ 不正确 -->
|列 1|列 2|
|--|--|
|数据 1|数据 2|下一步
GitHub Flavored Markdown 是软件开发中沟通和协作的强大工具。通过掌握这些功能，您可以创建更有效的文档、更好地跟踪问题，并与团队更高效地协作。