GitHub Flavored Markdown使用指南

发表于 更新于 分类于

GitHub Flavored Markdown (GFM) 是GitHub使用的Markdown方言，增加了一些额外的功能。本指南将详细介绍GFM的各种语法和特性，帮助你在GitHub上更好地编写文档。

基本Markdown语法

在了解GFM特有功能前，先回顾一下基本的Markdown语法：

标题

1
2
3
4
5
6
# 一级标题
## 二级标题
### 三级标题
#### 四级标题
##### 五级标题
###### 六级标题

强调

1
2
3
4
*斜体文本* 或 _斜体文本_
**粗体文本** 或 __粗体文本__
***粗斜体文本*** 或 ___粗斜体文本___
~~删除线文本~~

列表

无序列表：

1
2
3
4
- 项目1
- 项目2
  - 子项目2.1
  - 子项目2.2

有序列表：

1
2
3
4
1. 第一项
2. 第二项
   1. 子项2.1
   2. 子项2.2

链接和图片

1
2
[链接文本](https://example.com)
![图片替代文本](图片URL)

引用

1
2
3
> 这是一段引用文本
> 
> 引用可以有多个段落

代码

行内代码：

1
使用`code`标记行内代码

代码块：

1
2
3
4
5
6
​```
// 代码块
function hello() {
  console.log("Hello world!");
}
​```

GitHub Flavored Markdown特有功能

语法高亮代码块

GFM支持对代码块进行语法高亮，只需在代码块开始处指定语言：

1
2
3
4
5
​```javascript
function hello() {
  console.log("Hello world!");
}
​```

支持的语言包括但不限于：javascript, python, java, cpp, go, ruby, html, css, bash等。

任务列表

GFM支持可交互的任务列表：

1
2
3
- [x] 已完成任务
- [ ] 未完成任务
- [ ] @mentions, #refs, [links](), **formatting**, and ~~tags~~ 均支持

效果如下：

  • 已完成任务
  • 未完成任务
  • @mentions, #refs, links, formatting, and tags 均支持

表格

GFM支持创建表格：

1
2
3
4
| 表头1 | 表头2 | 表头3 |
|-------|-------|-------|
| 单元格1-1 | 单元格1-2 | 单元格1-3 |
| 单元格2-1 | 单元格2-2 | 单元格2-3 |

对齐方式：

1
2
3
| 左对齐 | 居中 | 右对齐 |
|:-------|:-----:|------:|
| 内容 | 内容 | 内容 |

自动链接

GFM会自动识别并链接URL：

1
访问 https://github.com

删除线

使用双波浪线标记删除线：

1
~~这是删除线文本~~

表情符号

GFM支持emoji表情符号：

1
:smile: :heart: :thumbsup: :tada:

常用表情符号：

  • :smile: - :smile:
  • :heart: - :heart:
  • :thumbsup: - :thumbsup:
  • :tada: - :tada:
  • :rocket: - :rocket:
  • :warning: - :warning:

完整表情符号列表可在这里查看。

提及用户和团队

在GitHub上，你可以使用@符号提及用户或团队：

1
2
@username
@organization/team-name

引用Issue和PR

使用#可以引用Issues和Pull Requests：

1
2
#123
organization/repository#123

引用提交

可以使用SHA引用特定的提交：

1
2
16c999e8c71134401a78d4d46435517b2271d6ac
organization/repository@16c999e

扩展语法

折叠部分

1
2
3
4
5
<details>
<summary>点击展开</summary>

这里是折叠的内容，可以包含任何Markdown格式。
</details>

效果：

点击展开

这里是折叠的内容，可以包含任何Markdown格式。

键盘按键

1
按下 <kbd>Ctrl</kbd>+<kbd>C</kbd> 复制文本。

效果：按下 Ctrl+C 复制文本。

定义列表

1
2
3
4
5
HTML
: 超文本标记语言，用于创建网页

CSS
: 层叠样式表，用于设计网页样式

脚注

1
2
3
这里有一个脚注[^1]。

[^1]: 这是脚注的内容。

数学公式

某些GitHub页面支持LaTeX格式的数学公式：

1
2
3
4
5
6
内联公式: $E=mc^2$

独立公式:
$$
E=mc^2
$$

最佳实践

  1. 使用相对链接：在仓库内引用文件时，使用相对链接而非绝对URL
  2. 合理使用标题层级：遵循层级结构，不要跳过层级
  3. 表格加入标题行：让表格更易读
  4. 长文档使用目录：可以使用[TOC]或手动创建目录
  5. 文档层次结构：使用统一的文件命名和目录结构
  6. 定期更新：保持文档与代码同步更新

常见问题

换行问题

在标准Markdown中，单个换行不会产生新段落。如需换行而不分段，可在行末添加两个或多个空格，或使用<br>标签。

转义字符

如果需要显示Markdown中的特殊字符，使用反斜杠\进行转义：

1
\*这不是斜体\*

兼容性问题

不同的Markdown解析器可能对某些语法有不同的处理方式。GFM有其特定的规范，某些语法可能在其他平台上不适用。

结语

GitHub Flavored Markdown为文档编写提供了丰富的功能，既保持了简洁性，又增强了表现力。熟练掌握GFM语法，将有助于更高效地在GitHub上进行协作和文档编写。