GitHub Flavored Markdown 书写和格式

GitHub Flavored Markdown 书写和格式

起笔时间：2025-07-15
完成时间：2025-07-17

参考：

文本文件

Markdown 格式文本以 .md .markdown 为文件后缀，文本的解析取决于解析器。解析器将 Markdown 文本转换为 HTML 格式，然后通过对 HTML 的渲染得到格式化文本内容。

基本语法

对于不同的解析器有不同的解析结果，不一样的语法格式在不同的解析器中可能有一样的效果。但是你应该学习一个更通用的、更广泛的、更受欢迎的一种格式作为“标准”，这会减少你的学习成本，为你学习其他内容的提供机会。

本文也是一个 Markdown 格式文本，由博客园选择提供文本解析，博客园选择的解析器不是为 GFM 设计的，对于部分特性是不支持的。

Markdown 文本最终将解析为 HTML 语法再渲染，因此 Markdown 支持 HTML 的语法。比如使用 <br /> 断行。

在基本语法中使用 * 标记的内容，如 *删除线 说明该语法属于高级特性，为了便于学习，在基本语法中纳入。

字符

Markdown 语法使用了很多字符或者字符组合来表示样式，如果你想让一些字符表示其本意，请使用转义字符 \ 或者 HTML 语法。

对于一些不便于通过键盘直接书写的字符，可以使用 HTML 实体引用和数字字符来表示。比如 &nbsp; &lt; &copy; &alpha; &frac34; &DifferentialD; &ClockwiseContourIntegral; 等。虽然这些内容将解析为对应字符，但不会用于语法表示来控制格式。

标题

创建标题使用一个至六个 # 来表示，# 的数量决定标题的结构层次和大小。

# 一级标题
## 二级标题
### 三级标题

文本样式

文本样式往往标签紧贴文本内容，不要使用空白符号用于控制格式（个人向），会导致格式失败。

样式 语法 示例 效果
加粗 ** ** 或者 __ __ **加粗文本** 加粗文本
斜体 * * 或者 _ _ _斜体文本_ 斜体文本
*删除线 ~~ ~~ ~~错误内容~~ 错误内容
上标 <sup> </sup> 上标<sup>superscript</sup> 上标superscript
下标 <sub> </sub> 下标<sub>subscript</sub> 下标subscript
下划线 <ins> </ins> <ins>下划线内容</ins> 下划线内容

嵌套： 你可以使用上述格式进行嵌套，比如在粗体文本中嵌套斜体、删除线、下划线，具体格式要因你的需求而使用，并遵循一种格式，可能由于解析器的原因会导致解析“失败”，不能达到你的预期。查看下面的示例以及效果截图。


嵌套示例 效果
**加粗文本中嵌入*斜体*示例一** 加粗文本中嵌入斜体示例1
**加粗文本中嵌入_斜体_示例2** 加粗文本中嵌入_斜体_示例2
__加粗文本中嵌入_斜体_示例3__ 加粗文本中嵌入_斜体_示例3
__加粗文本中嵌入*斜体*示例4__ 加粗文本中嵌入斜体示例4
*斜体文本中嵌入**加粗**示例1* 斜体文本中嵌入加粗示例1
*斜体文本中嵌入**加粗**示例1* 斜体文本中嵌入__加粗__示例2
*斜体文本中嵌入**加粗**示例1* 斜体文本中嵌入__加粗__示例3
*斜体文本中嵌入**加粗**示例1* 斜体文本中嵌入加粗示例4

注意！！！
下面是编辑本文时的截图（2025.7.15存于GitHub，可能无法正常显示或者与现在解析的结果不一样），你也许能看到在 * 中嵌套 _ 无法正常解析，但是使用其他 Markdown 工具，这种格式也许是有效的。

GFM Text Style


换行符

当你想断行构建格式，两个连续行文本有换行可能是不合适的，一些解析器不会将两行文本内容分隔，你可以采用下面的方式：

  • 在第一行文本末尾插入两个空格。
  • 在第一行文本末尾插入反斜杠\。
  • 使用断行符<br/>。

在两行间使用一个空行，将分离两行，两行之间也会有一个空行，这可能不是你的目标格式，请选择上面的一种方式进行换行。

特别的换行（分割线）

使用一条分割线进行换行，如下面的内容。当然对于不同的解析器可能有差异，比如---有些解析器会构建分割线，有的可能会构建标题。（应该规范你的语法，请不要在一个地方使用不同的语法，比如我的示例。）

第一行
___
第二行
***
第三行

效果：（这里没有使用“效果：”与实际效果的<hr />分割线）

第一行

第二行

第三行


段落

使用一个空行分割两个段落，如下面的内容。

第一段内容

第二段内容

引用文本

引用文本使用 >，使用多个 > 来构建多层次的引用，比如下面的示例。你应该注意到在多层次的引用中如何退出深层，使用一个引用空行。

> 引用文本 第1层
>> 引用文本 第2层
>
> 引用文本 第1层

效果：

引用文本 第1层

引用文本 第2层

引用文本 第1层


链接

使用方括号将链接文本包含，然后使用括号包含 URL 创建一个内联链接。

*章节链接

在基本链接的 URL 位置写入章节的标题定位点形成章节链接，标题定位点的生成使用以下规则：

  • 字母转换成小写模式。
  • 空格由连字符 - 表示。任何其他空格或者标点符号都将被删除。
  • 前导和尾随空格被删除
  • 如果标题的自动生成的定位点与同一文档中的早期定位点相同，那么通过追加连字符和自动递增整数来生成唯一标识符。

*自定义链接，自定义链接需要定义一个链接点，比如下表中的自定义链接，是在“章节链接”处加入了<a></a>标签。

链接示例

链接类型 语法 示例 效果
基本链接 [Content](URL "Title") [博客园](https://www.cnblogs.com/ "博客园") 博客园
*章节链接 [Content](URL "Title") [链接 小节](#链接 "链接") 链接 小节
*自定义链接 [Content](URL "Title") [章节链接 说明](#chapter-link "章节链接") 章节链接 说明

图像

图像是一种资源，同样使用 URL 来引用，为区分链接，使用一个前置感叹号。

链接类型 语法 示例 效果
链接 [Content](URL "Title") [博客园](https://www.cnblogs.com/) 博客园
图像 ![ALT](URL "Title") ![博客园LOGO](https://assets.cnblogs.com/logo.svg "博客园LOGO") 博客园LOGO

列表

无序列表

使用- * + 来构建无序列表，比如下面内容。（你可以在同一级列表中使用不一样的语法表示，不过你还是应该遵循更好的语法规范。）

GFM 基础知识点：
- 文本格式
- 引用
  + 引用文本
  + 引用代码
    * 行内引用
    * 块引用
- 链接
- 图像
- 列表
- ...

效果：

GFM 基础知识点：

  • 文本格式
  • 引用
    • 引用文本
    • 引用代码
      • 行内引用
      • 块引用
  • 链接
  • 图像
  • 列表
  • ...

有序列表

使用 1. 或者 1） 来构建有序列表，序号可以是数值或者字母等（取决于解析器），如下面内容。

Web前端知识学习：
1. Web前端基础
2. HTML
4. CSS
5) JavaScript

效果：

Web前端知识学习：

  1. Web前端基础
  2. HTML
  3. CSS
  1. JavaScript

你也许注意到，使用同一类型语法构建的有序列表会忽略序号错误，并且有序列表不同语法的列表项间有较大的间距。
这取决与解析器与渲染，在一些解析器上，有序列表使用不同的语法会构建两个列表，第二个列表以第一个列表项的序号作为起始序号。其他的解析器可能有不同的表现，比如可能会构建成多层次的列表。

你可以相互使用嵌套无序列表和有序列表，但是应该考虑你的解析器是否符合你语法表示的目标样式。列表层次使用缩进来控制（不同的解析器对缩进也有不同的控制）

高级格式

高级、拓展特性很大程度上取决于解析器实现。

引用代码

使用反引号 ` 来包含你需要引用的代码，行内引用内容应该使用一对单个反引号包含，如果是更复杂的代码块可以使用一对三个反引号包含``` ```。效果如下面的代码。

/*
 * print Hello
 */
void hello(){
    printf("Hello");
}

任务列表

任务列表在列表项前使用一个方括号控制，表示未完成的列表项在方括号中必须有一个空格，完成的列表项在方括号中使用字母 x 或者大写 X，示例语法如下。

TODO
- [x] 起床
- [X] 学习
- [ ] 饮食
- [ ] 锻炼
- [ ] 娱乐

效果：

TODO


表格

表格使用 | 分隔表格项，使用 --- :-- :-: --: 控制对齐样式。--- 是默认对齐，其具体对齐方向与解析器有关。控制样式上方的一行构成表头，只有更靠前的对齐控制有效。语法参考下面内容。

| 左对齐 | 居中 | 右对齐 |
| :-- | :-: | --: |
| 左对齐内容 | 居中内容 | 右对齐内容 |

效果：

左对齐 居中 右对齐
左对齐内容 居中内容 右对齐内容

脚注

使用方括号来构建脚注，如下面的内容。(脚注内容都生成在文章末尾)

你可以点击[博客园](https://www.cnblogs.com/ "博客园")[^1]。

[^1]: 开发者的网上家园。

效果：

你可以访问博客园[1]。


部分语法总结（表格）

部分语法格式总结如下（不便于说明、不便于采用示例的没有纳入）：

语法 示例 效果
转义 \ \* *
实体引用 &gt; >
标题 # ##...
加粗 ** ** 或者 __ __ **加粗文本** 加粗文本
斜体 * * 或者 _ _ _斜体_ 斜体
*删除线 ~~ ~~ ~~错误内容~~ 错误内容
上标 <sup> </sup> 上标<sup>superscript</sup> 上标superscript
下标 <sub> </sub> 下标<sub>subscript</sub> 下标subscript
下划线 <ins> </ins> <ins>下划线内容</ins> 下划线内容
换行符 \或者<br />
引用文本 > Quote text
链接 [Content](URL "Title") [博客园](https://www.cnblogs.com/ "博客园") 博客园
图像 ![ALT](URL "Title") ![博客园LOGO](https://assets.cnblogs.com/logo.svg "博客园LOGO") 博客园LOGO
无序列表 - list item 或者 + *
有序列表 1. first list item
引用代码 ` ` ``` ```
任务列表 - [x] finished list item

  1. 开发者的网上家园。 ↩︎

posted @ 2025-07-17 19:10  appleliushiqiD  阅读(22)  评论(0)    收藏  举报