这是一个展示如何编写 Markdown 文件的教程与示例，包括核心语法与常见扩展（GFM）。

Markdown

Markdown 概述

Markdown

Markdown 是一种轻量级标记语言，它允许人们使用易读易写的纯文本格式编写出结构化文档。

Markdown 语言在 2004 由约翰·格鲁伯（英语：John Gruber）与 Aaron Swartz 合作开发创建，在网站上被广泛使用。

CommonMark

CommonMark 是一种为 Markdown 制定的严格、明确的语法规范和测试套件。

它的核心目标是解决原始 Markdown 因规范不清晰而导致的“方言”林立、跨平台渲染不一致的痛点。

GFM

GitHub Flavored Markdown，通常缩写为 GFM，是 Markdown 的方言，目前在 GitHub.com 和 GitHub Enterprise 上为用户内容而支持。

GFM 是 CommonMark 的严格超集。GitHub 用户内容中支持的所有功能以及未在原始 CommonMark 规范中指定的功能，因此被称为 扩展，并且如此突出显示。

目录

在 Markdown 中，自动生成目录非常简单，只需要在恰当的位置添加 [TOC] 符号，凡是以 # 定义的标题都会被编排到目录中。

标题

Markdown 标题有两种格式：

使用 = 标记一级标题，使用 - 标记 二级标题。

使用 # 号标记。

三级标题

四级标题

五级标题

六级标题

段落

段落

段落后面使用一个空行来表示重新开始一个段落。

第一段落

第二段落

换行

在行尾添加两个及以上的空格表示换行，类似于直接加上 HTML 换行标签 <br>

第一行
第二行
第二行

多使用「段落」标记，少用或者不用「换行」标记。

文本与着重

斜体

斜体字体表示强调或引用，通常用于书名、外语词汇等的强调。

斜体语法使用一个星号 * 或一个下划线 _ 包围文字。

斜体文本italic text

建议在强调符号前后加空格以提高可读性

粗体

加粗字体可以使重要信息更加突出。

粗体语法使用一个星号 ** 或一个下划线 __ 包围文字。

粗体文本

bord text

建议在强调符号前后加空格以提高可读性

粗斜体组合

粗斜体组合可以使用三个星号 *** 或三个下划线 ___ 包围文字。

粗斜体italic bord text

建议在强调符号前后加空格以提高可读性

删除线

在文字的两端加上两个波浪线 ~~ 表示文字已过时或删除

普通文字

_{删除的文字}

下划线

Markdown 没有内置的下划线语法，但可以通过 html 标签 <u> 实现。

用下划线可能会干扰阅读，因此应尽量少用。

带下划线的文本

高亮

文本高亮不是标准 Markdown 语法，但许多扩展支持，或是通过 HTML 实现：

这是 ==高亮文本==

这是 高亮文本

列表

Markdown 支持有序列表和无序列表。

无序列表

无序列表使用星号 *、加号 + 或是减号 - 作为列表标记，这些标记后面要添加一个空格，然后再填写内容。

• 第一项
• 第二项
• 第三项

• 第一项
• 第二项
• 第三项

• 第一项
• 第二项
• 第三项

建议：

1. 统一使用减号 -，因为它在视觉上更清晰
2. 在同一文档中保持一致的标记方式

有序列表

有序列表使用数字并加上点 . 来表示。

1. 第一项
2. 第二项
3. 第三项

Markdown 会从开头数字开始，自动修正数字顺序。

4. 第四项
5. 第六项（实际显示为 5）
6. 第八项（实际显示为 6）

列表嵌套

列表嵌套只需在子列表中的选项前面添加四个空格即可。

1. 第一项：
   • 第一个子项
     1. 第一个子子项
     2. 第一个子子项
   • 第一个子项
2. 第二项：
   1. 第一个子项
   2. 第二个子项

建议：

1. 子列表需要缩进 2-4 个空格
2. 保持一致的缩进长度
3. 可以无限层嵌套，但实际使用中建议不超过 3 层

引用

引用块用于突出显示重要信息、引用他人观点或创建视觉层次。

引用块

区块引用是在段落开头使用 > 符号 ，然后后面紧跟一个 空格 符号：

区块内可以使用 其他语法。

这是引用内容 这是引用内容 这是引用内容

引用区块中的列表：

1. 第一项
2. 第二项
   1. 第一个元素
   2. 第二个元素

引用区块中的代码：

列表中的引用块

如果要在列表项目内放进区块，那么就需要在 > 前添加四个空格的缩进。

1. 第一项

   区块引用

2. 第二项

   区块引用

嵌套引用块

一个 > 符号是最外层，两个 > 符号是第一层嵌套。

最外层

第一层嵌套

第二层嵌套

代码

行内代码

如果是段落上的一个函数或片段的代码可以用反引号把它包起来。

在这个段落中我们提到了 print() 函数

反引号转义

当需要在行内代码中显示反引号或其他特殊字符时，需要进行转义处理。

使用多个反引号包围反引号。

多个反引号 ` 包围

在行内代码中无法使用反斜杠转义

缩进式代码区块

缩进式代码区块使用 4 个空格或者一个制表符（Tab 键）。

正常文本段落

正常文本段落

三反引号代码块

可以用 ``` 包裹一段代码，并指定一种语言（也可以不指定）：

链接

链接语法可以为 Markdown 文档提供交互性的导航功能。

使用中括号 [] 和括弧 ()

这是一个链接 baidu

使用砖石符号 <>

这是一个链接 https://www.baidu.com

自动链接识别

现代 Markdown 解析器通常支持自动识别 URL 和邮箱地址

网址：https://www.example.com 邮箱：example@email.com

自动识别功能依赖于具体的 Markdown 解析器，为了确保兼容性，建议使用标准的链接语法。

参考链接

我们可以通过变量来设置一个链接，变量赋值在文档末尾进行，类似于脚注。

这个链接用第二个方括号 [a] 作为网址变量 google

这个链接省略第二个方括号作为网址变量 baidu

锚点链接

锚点链接用于在同一文档内跳转，特别适合长文档的导航。

跳转到标题 Markdown 概述

跳转到 自定义位置

回到顶部

注释

原生注释

这是一段没有被注释的文字

通过 Markdown 自身的解析功能

这是一段没有被注释的文字

使用 HTML 样式实现隐藏

这是一段没有被注释的文字

图片

引用与展示图片

使用 ![替代文本](图片路径或URL "图片标题") 引用图片

本地图片

网络图片（图床图片）

指定图片属性

Markdown 还没有办法指定图片的属性，如果你需要的话，你可以使用 HTML 的 <img> 标签。

表格

表格能够清晰地展示结构化数据。

制作表格

Markdown 制作表格使用 | 来分隔不同的单元格，使用 - 来分隔表头和其他行。

我们可以设置表格的对齐方式：

表格对齐方式

---: 设置内容和标题栏居右对齐。 :--- 设置内容和标题栏居左对齐。 :---: 设置内容和标题栏居中对齐。

表格内容多元化

竖线转义

您可以使用表格的 HTML 字符代码或者反斜杠转义在表中显示竖线 | 字符。

HTML

不在 Markdown 涵盖范围之内的标签，都可以直接在文档里面用 HTML 撰写。

行内级联标签

HTML 的行级內联标签如 <span>、<cite>、<del> 不受限制，可以在 Markdown 的段落、列表或是标题里任意使用。依照个人习惯，甚至可以不用 Markdown 格式，而采用 HTML 标签来格式化。

表示按键组合： Ctrl + Alt + Del
表示粗体： 加粗文本
表示斜体： 斜体文本
表示语义强调： 被强调的文本
添加上标和下标： ^上标 _下标
表示链接： example
表示换行：第一行
第二行

区块标签

区块元素 ── 比如 <div>、<table>、<pre>、<p> 等标签，必须在前后加上空行，以便于内容区分。

这是一个正常段落。

HTML 实体

Markdown 不能直接插入特殊符号，但可以复制粘贴，或者使用 HTML 实体：

版权 (©) — ©
注册商标 (®) — ®
商标 (™) — ™
欧元 (€) — €
左箭头 (←) — ←
上箭头 (↑) — ↑
右箭头 (→) — →
下箭头 (↓) — ↓
度数 (°) — °
圆周率 (π) — π

其他

分隔线

用三个以上的星号 *、减号 - 来建立一个分隔线，行内不能有其他东西。

转义

要显示原本用于格式化 Markdown 文档的字符，请在字符前面添加反斜杠字符 \ ，使用反斜杠转义特殊字符

注意某些解析器由于内部特殊逻辑，可能会出现显示的异常，例如 VitePress 直接吞掉 { }，NuxtContent MPC 直接吞掉 [ ]，建议使用额外代码进行恢复。

参考资料

CommonMark - CommonMark 规范

GitHub Flavored Markdown Spec | GFM

Markdown 教程 | 菜鸟教程

Markdown 教程 — 最简明的 Markdown 语法入门指南