学习 GitHub 风格的 Markdown 语法和格式化 - 带有示例

Markdown 是一种轻量级、开源、易读易写的文本格式化方法，你可以在任何 IDE 或编辑器中将其作为纯文本使用。

在 GitHub 上写作时，你可以使用 Markdown 语法和 HTML 元素来扩展 Markdown 的功能。你可以在 GitHub 的各个地方使用 Markdown 语法，比如 README 文件、wiki、评论、拉取请求以及创建问题时。

对于每个软件开发者来说，学习 Markdown 是你职业生涯道路上的一个关键步骤。

为了增强 Markdown 的基本功能，GitHub 添加了一些自定义功能，并创建了 GitHub 风格的 Markdown。通过这个，你可以通过提及用户、问题和 PR 引用以及添加表情符号来轻松与其他用户在拉取请求和问题中进行交流。

本文将教你 GitHub 风格的 Markdown 的基础知识，以便你能够在你的项目中开始使用它。

（本文视频讲解：java567.com）

GitHub 风格的 Markdown 语法

GitHub 风格的 Markdown 语法分为两个部分。

1. 基本格式化语法
2. 高级格式化语法

我们将在下面详细讨论每一个。

基本格式语法

基本格式语法适用于所有人。它包含了诸如标题、代码、图片、引用、链接等基本要素，这些是你在撰写文档时需要了解的内容。

1. 标题
2. 段落
3. 注释
4. 文本样式
5. 引用
6. 代码
7. 链接
8. 图片
9. 列表
10. 提及个人和团队
11. 引用问题和拉取请求
12. 使用表情符号
13. 脚注
14. 警告

请注意，代码示例大多来自于 GitHub 的文档。

标题

你可以使用 # 符号来创建标题。一个 # 创建一个 H1 标题，两个创建一个 H2 标题，依此类推，就像这样：

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

在 Markdown 中创建标题。

段落

要创建段落，你可以使用空行来分隔一行或多行文本或段落。

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Etiam est odio, commodo id diam sed, pulvinar sagittis tortor. Nam vestibulum purus eros. Sed congue, mi id pretium auctor, nibh augue iaculis arcu, eu tristique quam dolor at erat.

Quisque vel odio condimentum, mollis sem vitae, porta diam. Praesent ligula elit, condimentum eget ex sed, commodo sollicitudin sapien.

Proin volutpat faucibus nulla. Nullam eros sem, ultricies gravida nunc nec, dapibus posuere nisl. Nunc lacinia elementum turpis in pharetra. Aenean eu neque eros.
1
2
3
4
5

在 Markdown 中创建段落。

注释

注释几乎在每种编程语言中都可用。它们帮助开发者写下注释并向他们的代码添加额外信息，帮助其他开发者理解正在发生的事情以及代码如何运行。

要在 Markdown 中添加注释和额外信息，请使用以下语法：<!--- 包裹文本 --->。

以下是一个示例：

<!-- 这段内容不会出现在渲染后的 Markdown 中 -->
1

在 Markdown 中创建注释。

文本样式

你可以对文本应用基本样式，比如粗体、斜体、删除线、下标或上标，以提高可读性并更清晰地传达你的意思。

1. 对于 粗体，你可以使用以下语法：**你的文本**
2. 对于 斜体，你可以使用以下语法：*你的文本* 或 _你的文本_。
3. 对于 删除线，你可以使用以下语法：~~你的文本~~
4. 对于 下标，你可以使用以下语法：下标<sub>文本</sub>在此。
5. 对于 上标，你可以使用以下语法：上标<sup>文本</sup>在此。

## 粗体

**你的文本**

## 斜体

*你的文本*
_你的文本_

## 删除线

~~你的文本~~

## 下标

下标<sub>文本</sub>在此。

## 上标

上标<sup>文本</sup>在此。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

引用

块引用或引用是格式化为让读者知道你在引用某人的句子或段落。要在 Markdown 中创建块引用，可以使用 > 符号。

> 这是引用的文本
1

在 Markdown 中创建块引用或引用。

代码

Markdown 文件支持两种类型的代码示例：内联和代码块。

1. 要在 Markdown 文件中添加代码块，请使用以下语法：你的代码 。
2. 要将内联代码添加到 Markdown 文件中，请使用以下语法：你的代码。

## 代码块

1
2

// ES5 语法
var multiply = function(x, y) {
return x * y;
};

// ES6 箭头函数
var multiply = (x, y) => { return x * y; };

// 或者更简单地
var multiply = (x, y) => x * y;

## 内联代码 

JavaScript 提供三种不同的值比较操作：使用 `===` 进行严格相等比较，使用 `==` 进行宽松相等比较，以及使用 `Object.is()` 方法。
1
2
3
4

要在代码块中支持代码高亮，你可以在三个反引号之后添加一个可选的语言标识符（就像下面的示例中的 JavaScript 一样）：

## 代码块

```javascript

// ES5 语法
var multiply = function(x, y) {
  return x * y;
};

// ES6 箭头函数
var multiply = (x, y) => { return x * y; };

// 或者更简单地
var multiply = (x, y) => x * y;   

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

创建一个带有语法高亮示例的代码块。

链接

Markdown 文件将链接分为两类：内联和相对。

内联链接

要在 Markdown 文件中创建内联链接，请将链接文本放在方括号 [ ] 中，紧接着在括号 ( ) 中放置 URL。

This site was built using GitHub Pages.
1

相对链接

相对链接与内联链接类似，但在 [] 部分有所不同：[] 部分包含存储库中文件的路径。

你可以使用相对链接来链接两个文件：例如，将 CONTRIBUTING 文件链接到 README 文件中。

[贡献指南](docs/CONTRIBUTING.md)
1

以 / 开头的相对链接将相对于存储库根目录。你可以使用所有相对链接操作符，比如 ./ 和 ../：

[贡献指南](../docs/CONTRIBUTING.md)
1

图片

要在 Markdown 文件中添加图片，首先在 [] 中放置 alt 文本，然后在括号 () 中放置图片链接。

看起来像这样：

1

列表

列表有助于按顺序记录重要信息，这对读者非常重要，使人们易于理解和查找信息。

Markdown 文件支持三种类型的列表：

1. 有序列表
2. 无序列表
3. 任务列表

有序列表

第一种类型是有序列表。要创建有序列表，请以数字加句点开头。

1. one
2. two
3. three
4. four
1
2
3
4

创建一个有序列表

无序列表

第二种类型是无序列表。要创建无序列表，请使用 -、+ 或 *（取决于你的喜好 - 它们都会呈现为无序列表）：

* 第一项
* 第二项
* 第三项
* 第四项


- 第一项
- 第二项
- 第三项
- 第四项

+ 第一项
+ 第二项
+ 第三项
+ 第四项
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

创建一个无序列表

任务列表

第三种类型是任务列表。要创建任务列表，列表项以连字符开头，后跟一个空格，然后是方括号 []。你可以在方括号 [x] 中使用 x 来标记任务为已完成。

- [x] #739
- [ ] https://github.com/octo-org/octo-repo/issues/740
- [ ] 当所有任务完成时，为体验添加喜悦 :tada:
1
2
3

在 markdown 中添加任务列表

提及个人和团队

在 markdown 中提及用户和团队

要在 GitHub markdown 文件中提及个人或团队，请键入 @，然后写入用户名或团队用户名。

## 个人或个体用户名

@officialrajdeepsingh，请查看以下更改。

## 团队或公司
博客主题部分由 @frontendweb 维护
1
2
3
4
5
6

在 markdown 中提及其他用户和团队

引用问题和拉取请求

问题和拉取请求

要在 GitHub markdown 文件中提及问题和拉取请求，请键入 #，然后键入问题或拉取请求的编号或标题。然后按 tab 键或 enter 键以完成高亮显示的结果。

删除默认 _target blank 中的徽标 #93
1

在 markdown 中提及拉取请求

使用表情符号

在 markdown 中添加表情符号。

要在你的写作中添加表情符号，请在两个冒号之间键入表情符号的代码。如果只键入 :，GitHub 上将显示建议的表情符号列表。

找到你想要的表情符号后，按 Tab 键或 Enter 键选择高亮显示的结果。

不要忘记给我们的仓库点颗星！ :star:
1

在 markdown 中添加表情符号

脚注

要添加脚注引用，请在方括号 [^1] 内添加一个尖号和一个标识符，使用以下语法：

这是一个简单的脚注,[^1] 这是一个更长的脚注.[^bignote]

[^1]: 这是第一个脚注。

[^bignote]: 这是一个包含多个段落和代码的脚注。
1
2
3
4
5

在 markdown 中创建一个脚注

警告

警告是基于块引用语法的 Markdown 扩展，你可以使用它来强调重要信息。

GitHub 风格的 Markdown 支持五种类型的警告：[!NOTE]、[!TIP]、[!IMPORTANT]、[!WARNING] 和 [!CAUTION]。你可以使用其中任何一个：

> [!NOTE]
> 有用的信息，用户在浏览内容时应该知道。

> [!TIP]
> 提供更好或更容易做事的有益建议。

> [!IMPORTANT]
> 用户为了实现目标所需的关键信息。

> [!WARNING]
> 紧急信息，需要用户立即注意以避免问题。

> [!CAUTION]
> 关于某些操作的风险或负面结果的建议。
1
2
3
4
5
6
7
8
9
10
11
12
13
14

在 markdown 语法中，GitHub 风格的 Markdown 支持的警告列表。

警告语法在浏览器中如下所示：

在 markdown 中添加警告示例。

高级格式化语法

这个高级格式化语法部分包含了一些高级用法，比如添加图表和表格、折叠节、数学表达式等。

1. 创建表格
2. 创建折叠节
3. 创建图表
4. 数学表达式

创建表格

要在 Markdown 中创建表格，你可以使用管道 | 和连字符 -。连字符用于创建列标题，而管道用于分隔列。

| 第一标题 | 第二标题 |
| --------- | --------- |
| 内容单元 | 内容单元 |
| 内容单元 | 内容单元 |
1
2
3
4

在 markdown 中创建表格

表格在浏览器中的样子如下：

Markdown 中的表格示例。

创建折叠节

要在 markdown 文件中创建一个折叠节，你可以使用 <details> 标签。这个标签是一个 HTML 元素，你可以很容易地使用它来扩展 GitHub 风格的 Markdown 的功能。下面是它的工作原理：

<details>
  <summary>点击这里。 </summary>
   
   ### 在这里添加消息

   你可以在折叠节中添加文本。 

   你也可以添加图片或代码块。

   ```ruby
     puts "Hello World"
   ```
  
</details>
1
2
3
4
5
6
7
8
9
10
11
12
13
14

在 markdown 中创建一个折叠节

在浏览器中，折叠语法看起来像这样：

Markdown 中的折叠示例。

创建图表

要向 Markdown 文件中添加图表，使用三个反引号并将它们包裹在四个反引号内。然后，告诉使用了哪个标识符（Mermaid、GeoJSON、TopoJSON、ASCII STL）来创建图表。

GitHub 支持使用四种语法来创建图表：mermaid、geoJSON、topoJSON 和 ASCII STL。

1. Mermaid
2. GeoJSON 和 TopoJSON
3. ASCII STL

Mermaid

Mermaid 是一个受 Markdown 启发的工具，可以将文本渲染成图表。你可以使用 Mermaid 创建流程图、序列图、饼图等。

GitHub 风格的 Markdown 扩展了使用 Mermaid 的功能。

你可以在 Markdown 中创建流程图、序列图、饼图等。GitHub 会处理剩下的部分。那么你如何在屏幕上渲染图表呢？

```mermaid
graph LR;
   A --  和 --> B -- 到 --> C
```
1
2
3
4

创建 Mermaid 示例

在浏览器中，mermaid 语法看起来像这样。

Markdown 中的 Mermaid 示例。

GeoJSON 和 TopoJSON

你可以使用 GeoJSON 或 TopoJSON 在 GitHub 仓库的 README 文件或 GitHub Wiki 中添加交互式地图。

你可以使用代码块语法添加交互式地图。

1. GeoJSON 可以通过指定坐标来创建地图。要添加交互式地图，请使用以下语法：geojson 你的代码
2. TopoJSON 可以通过指定坐标和形状来创建地图。要添加交互式地图，请使用以下语法：topojson 你的代码

使用 GeoJSON 的示例：

```geojson
{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "id": 1,
      "properties": {
        "ID": 0
      },
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
              [-90,35],
              [-90,30],
              [-85,30],
              [-85,35],
              [-90,35]
          ]
        ]
      }
    }
  ]
}
```
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

在 markdown 中创建 geojson

TopJSON 的示例：

```topojson
{
  "type": "Topology",
  "transform": {
    "scale": [0.0005000500050005, 0.00010001000100010001],
    "translate": [100, 0]
  },
  "objects": {
    "example": {
      "type": "GeometryCollection",
      "geometries": [
        {
          "type": "Point",
          "properties": {"prop0": "value0"},
          "coordinates": [4000, 5000]
        },
        {
          "type": "LineString",
          "properties": {"prop0": "value0", "prop1": 0},
          "arcs": [0]
        },
        {
          "type": "Polygon",
          "properties": {"prop0": "value0",
            "prop1": {"this": "that"}
          },
          "arcs": [[1]]
        }
      ]
    }
  },
  "arcs": [[[4000, 0], [1999, 9999], [2000, -9999], [2000, 9999]],[[0, 0], [0, 9999], [2000, 0], [0, -9999], [-2000, 0]]]
}
```
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

在 markdown 中创建一个 TopJson

ASCII STL

GitHub Flavored Markdown 支持 STL 语法。STL 语法允许你在 markdown 中添加交互式 3D 模型。你可以使用以下语法：stl 你的代码.

```stl
solid cube_corner
  facet normal 0.0 -1.0 0.0
    outer loop
      vertex 0.0 0.0 0.0
      vertex 1.0 0.0 0.0
      vertex 0.0 0.0 1.0
    endloop
  endfacet
  facet normal 0.0 0.0 -1.0
    outer loop
      vertex 0.0 0.0 0.0
      vertex 0.0 1.0 0.0
      vertex 1.0 0.0 0.0
    endloop
  endfacet
  facet normal -1.0 0.0 0.0
    outer loop
      vertex 0.0 0.0 0.0
      vertex 0.0 0.0 1.0
      vertex 0.0 1.0 0.0
    endloop
  endfacet
  facet normal 0.577 0.577 0.577
    outer loop
      vertex 1.0 0.0 0.0
      vertex 0.0 1.0 0.0
      vertex 0.0 0.0 1.0
    endloop
  endfacet
endsolid
```
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

在 markdown 中创建一个 ASCII STL

在浏览器中，STL 语法看起来像这样：

Markdown 中的 STL 示例。

数学表达式

你可以向 GitHub markdown 文件中添加数学表达式，比如方程、术语、公式等。GitHub 使用 LaTeX 格式嵌入在 Markdown 中。有两种方法可以添加这些表达式：

1. 写内联数学表达式
2. 将数学表达式写成代码块

写内联数学表达式

内联数学表达式以 $ 开头，以 $ 结尾。

内联数学表达式示例：$\sqrt{3x-1}+(1+x)^2$
1

内联数学表达式示例

在浏览器中，内联数学语法看起来像这样：

内联数学表达式示例

将数学表达式写成代码块

要将数学表达式的代码块添加到 Markdown 文件中，请使用 ````math` 代码块，并用 `````反引号将其包裹起来，以将表达式显示为块。

要将数学表达式的代码块添加到 Markdown 文件中，请使用 ````math 代码块，并用三个反引号将其包裹起来，以将表达式显示为块。

```math
\left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \left( \sum_{k=1}^n b_k^2 \right)
```
1
2
3

代码块数学表达式示例

在浏览器中，数学代码块语法看起来像这样：

代码块数学表达式示例

结论

Markdown 语法在 GitHub 和其他所有中心 Git 服务器（如 GitLab、Gitea 等）中都可以很好地工作。

不同的工具对它们的 markdown 命名方式不同。例如，GitHub 以自己的方式扩展了 markdown 的功能，并构建了 GitHub Flavored Markdown。GitLab 也扩展了 markdown 的功能，并构建和创建了 GitLab-flavored markdown。

Markdown 语法在每个 Git 服务中大多是相同的。但是警告、图表和其他一些功能只在 GitHub Flavored Markdown 中有效。

（本文视频讲解：java567.com）