Markdown 实用指南

文本格式化

加粗

语法： **粗体**/__粗体__。
效果：粗体。

最佳实践：尽可能使用**粗体**。

斜体

语法： *斜体*/_斜体_。
效果：斜体。

最佳实践：尽可能使用*斜体*。

删除线

语法： ~~删除线~~。
效果：~~删除线~~。

下划线（HTML）

Markdown 本身不支持下划线，但是可以通过 HTML 标签实现。

语法： 下划线（HTML）。
效果：下划线（HTML）。

高亮

语法： ==高亮==。
效果：高亮。

不是所有 Markdown 解析器都支持此语法，届时可以使用对应 HTML 语法（高亮）来实现。

上下标

上标
- 语法：x^2^。
- 效果：x²。
下标
- 语法：H~2~O。
- 效果：H₂O。

不是所有 Markdown 解析器都支持此语法，届时可以使用对应 HTML 语法（上标/下标）来实现。

其他

由于 Markdown 兼容 HTML，因此必要时可以使用 HTML 来实现更复杂的效果。

链接

语法： 全球最大的开发者社区：[GitHub](https://github.com)。
效果：全球最大的开发者社区：GitHub。

相对链接

链接的 URI 可以使用相对路径，来引用基于当前文件的相对位置的资源，比如 Git 仓库的 README 文件中通常这样引用许可证文件：[Mozilla Public License 2.0](LICENSE)。

链接的 Title

鼠标悬停在链接上时的提示文本。

语法： [GNU](https://www.gnu.org "伟大，无需多言。")。
效果：GNU。

字面 URL

字面 URL，不同于超链接，将文本指向一个 URL，而是将 URL 原样写出来。

语法： <https://www.markdownguide.org/>。
效果：https://www.markdownguide.org/。

邮箱链接

语法： <gnu@gnu.org>。
效果：gnu@gnu.org。

图像

语法：

![GNU Logo](https://www.gnu.org/graphics/gerwinski-gnu-head.png)

效果：

GNU Logo

图像 Title

同链接。

图像链接

语法：

[![GNU Logo](https://www.gnu.org/graphics/gerwinski-gnu-head.png)](https://www.gnu.org/)

效果：

控制图片尺寸（HTML）

语法：

<img src="https://www.linux.org/images/logo.png" alt="Linux Logo" width="300" height="45" />

效果：

引用块

语法：

> GNU's Not Unix!

效果：

GNU’s Not Unix!

折叠块/详情块（HTML）

此语法并不是 Markdown 的常客，但有些项目的 README.md 中会使用此语法。

语法：

<details>
<summary>点击展开查看详情</summary>

这里是折叠的内容，可以包含 Markdown 语法。

- 列表项 1
- 列表项 2
</details>

效果：

点击展开查看详情

这里是折叠的内容，可以包含 Markdown 语法。

列表项 1
列表项 2

列表

有序列表

语法：

编写程序的 7 个步骤：

1. 定义程序的目标；
2. 设计程序；
3. 编写代码；
4. 编译；
5. 运行程序；
6. 测试和调试；
7. 维护和修改。

效果：

编写程序的 7 个步骤：

定义程序的目标；
设计程序；
编写代码；
编译；
运行程序；
测试和调试；
维护和修改。

无序列表

语法：

主流 Web 框架：

- React
- Vue
- Astro

效果：

主流 Web 框架：

React
Vue
Astro

定义列表

语法：

Markdown
: 一种轻量级标记语言
: 用于编写格式化文本

HTML
: 一种用于创建网页的标记语言

效果：

Markdown: 一种轻量级标记语言; 用于编写格式化文本
HTML: 一种用于创建网页的标记语言

分割线

语法：

---

效果：

代码

行内代码

语法：

在 C 语言中打印“Hello world!”：`printf("Hello world!\n");`。

效果：

在 C 语言中打印“Hello world!”：printf("Hello world!\n");。

当需要在行内代码中包含反引号时，则外层需要使用双反引号包裹：

语法：

JavaScript 模板字面量：``let greeting = `Hello, ${name}`;``。

效果：

JavaScript 模板字面量：let greeting = `Hello, ${name}`;。

代码块

语法：

```c
#include <stdio.h>

int main(void) {
    printf("Hello world!\n");
    return 0;
}
```

效果：

#include <stdio.h>

int main(void) {
    printf("Hello world!\n");
    return 0;
}

当需要在代码块中包含代码块语法时，则外层需要使用四个反引号包裹，比如刚才的示例就是这样实现的：

````markdown
```c
#include <stdio.h>

int main(void) {
    printf("Hello world!\n");
    return 0;
}
```
````

更深层的嵌套（不建议），则需要更多反引号，以上示例就使用了五个反引号来实现。

进阶语法

转义字符

Markdown 语法中涉及到的字符，如果想正常显示，则需要使用反斜杠（\）转义。

表格

语法：

| 网站 | 说明 | 评分 |
| ---: | :---: | :--- |
| [GitHub](https://github.com) | 全球最大的开发者社区。 | ⭐⭐⭐⭐⭐ |
| [GNU](https://www.gnu.com) | GNU's Not Unix! | ⭐⭐⭐⭐ |

---:、:---、:---: 分别表示对应列右、左、居中对齐。

对应的 HTML 语法：

效果：

网站	说明	评分
GitHub	全球最大的开发者社区。	⭐⭐⭐⭐⭐
GNU	GNU’s Not Unix!	⭐⭐⭐⭐

表格的跨行跨列（HTML）

Markdown 本身不支持表格跨行跨列，但是可以通过 HTML 语法来实现，可以参考允许单元格跨越多行和列 - HTML 表格基础 - 学习 Web 开发 | MDN，本文不再赘述。

脚注

在 Markdown 中，脚注的两个部分（脚注引用和脚注定义）即使写在一块（通常也建议写在一块），在渲染的时候，通常也会将脚注定义渲染在文档尾部（如果没有的话，就需要手动放在末尾），不然为什么叫脚注呢？

语法：

GNU/Linux[^1] 是一个伟大的开源项目。

[^1]: GNU/Linux 指的是将 GNU 项目的软件组件与 Linux 内核结合而成的操作系统。

效果：

GNU/Linux^[1] 是一个伟大的开源项目。

待办列表

语法：

- [ ] 完成用户登录模块
- [x] 修复支付回调 Bug
- [ ] 优化数据库查询性能
- [ ] 编写接口文档
- [ ] Code Review

锚点

锚点，即在同一个页面中使用超链接语法跳转到不同的位置。只要在需要跳转的目标位置（通常是标题处，但其实任何位置都可以）放置一个空的 a 元素，并给这个 a 元素添加一个 id 属性，此后就可以使用 #id 作为该位置的 url，使用超链接语法引用这个锚点了。

语法：

以下示例，将 <a id="anchor-advanced-grammar"></a> 放在了文章之前的位置。

## 进阶语法<a id="anchor-advanced-grammar"></a>

……

[进阶语法](#anchor-advanced-grammar)

效果：

进阶语法

由于是 id 属性，因此需要确保唯一性。而很多 Markdown 解析器默认会给每个标题添加一个 id 属性（大多数解析器会将标题转换为小写、空格变连字符，例如：## Hello World → #hello-world），需要注意不要与现有标题的 id 冲突。

内容目录

语法：

[TOC]

效果：

高级语法

LaTeX 数学公式

行内公式

语法：

“上帝公式”：$e^{i\pi}+1=0$

效果：

“上帝公式”： $e^{i\pi}+1=0$

块级公式

语法：

$$
E=mc^2
$$

效果：

$E=mc^2$

常用 LaTeX 语法

语法名称	说明	语法	效果
上标（指数）与下标	`^` 表示上标（通常是指数），`_` 表示下标。	$x_i^2$	$x_i^2$
分式（fraction）	`\frac{分子}{分母}`。	$\frac{1}{2}$	$\frac{1}{2}$
根号（square root）	`\sqrt[根指数]{被开方表达式}`。	$\sqrt[2]{x^2+y^2}$	$\sqrt[2]{x^2+y^2}$
求和（sum）	`\sum_{求和下限}^{求和上限} {通项公式}`。	$\sum_{i=1}^n i^2$	$\sum_{i=1}^n i^2$
积分（integral）	`\int_{积分下限}^{积分上限} {被积表达式}`； `\infty` 表示无穷符号。	$\int_0^\infty e^{-x}dx$	$\int_0^\infty e^{-x}dx$
矩阵（matrix）	`\begin{matrix} {矩阵元素} \end{matrix}`；矩阵元素之间用`&`连接，用`\\`换行。	$\begin{matrix} a & b & c \\ d & e & f \\ f & g & h \end{matrix}$	$\begin{matrix} a & b & c \\ d & e & f \\ f & g & h \end{matrix}$

更多 LaTeX 语法参考 LaTeX Documentation。

Emoji

Emoji，即表情符号，在 Markdown 中，可以直接使用 Emoji 符号，也可以使用 Emoji Shortcode（冒号语法）来表示 Emoji。

语法：

😎 :sunglasses:

效果：

😎 😎

完整的 Emoji Shortcode 列表参考 Emoji Shortcodes - Emojipedia。

图表

在 Markdown 中，使用 Mermaid 语法来绘制图表，Mermaid 支持多种图表类型，这里介绍 5 种常用的图表类型：流程图、序列图、类图、状态图以及实体关系图。

在 Markdown 中绘制 Mermaid 图表的语法大体是相同的，就是使用代码块语法，指定语言为 mermaid，然后在代码块中编写 Mermaid 语法。

流程图

要绘制 Mermaid 流程图（Flowchart），需要在开头使用 flowchart（推荐）或 graph 关键字，并在其后指定流程图的方向，四种方向的指定方法：

TB / TD：从上到下；
BT：从下到上；
LR：从左到右；
RL：从右到左。

这里演示最常用的 TD 方向。

然后定义节点和连接它们的线：

定义节点：使用标识符（通常是单个的大写字母）定义节点，在其后使用括号包裹其内容，可以使用不同的括号包裹节点的内容来定义节点的形状，常用节点形状有：
- []：矩形节点；
- ()：圆角矩形节点；
- {}：菱形节点。
定义连接线，常用连接线样式有：
- ---、-->：实线、实线箭头；
- -.-、-.-> ：虚线、虚线箭头；
- ===、==>：加粗线、加粗箭头。
定义连接线上的描述文字（可选）：在连接线后面，使用 | 包裹描述文字，如 A --> |描述文字| B 。

另外可以使用 subgraph 创建子流程。

语法：

```mermaid
flowchart TD
    A[开始] --> B{是否登录?}
    B -- 是 --> C[进入首页]
    B -- 否 --> D[跳转登录页]
```

效果：

flowchart TD
    A[开始] --> B{是否登录?}
    B -- 是 --> C[进入首页]
    B -- 否 --> D[跳转登录页]

序列图

要绘制 Mermaid 序列图（Sequence Diagram），需要在开头使用 sequenceDiagram 关键字。

然后定义参与者和它们之间的消息交互：

定义参与者：使用 participant 关键字定义参与者（可以是人、系统或组件），也可以使用别名来简化引用；
定义消息类型，常用消息样式有：
- ->>：实线箭头（同步消息）；
- -->>：虚线箭头（异步消息/返回消息）；
- ->：实线无箭头（用于注释等）；
- --x：带叉的虚线（表示销毁或终止）。
定义消息上的描述文字：在箭头后面使用冒号加描述文字，如 A ->> B: 发送请求。

另外可以使用 alt、opt、loop 等关键字创建条件分支、可选流程和循环。

语法：

```mermaid
sequenceDiagram
    participant 用户
    participant 服务器

    用户->>服务器: 发送请求
    服务器-->>用户: 返回响应
```

效果：

sequenceDiagram
    participant 用户
    participant 服务器

    用户->>服务器: 发送请求
    服务器-->>用户: 返回响应

类图

要绘制 Mermaid 类图（Class Diagram），需要在开头使用 classDiagram 关键字。

然后定义类和它们之间的关系：

定义类：使用 class 关键字定义类，在大括号中声明类的属性和方法；
- 属性/方法的可见性前缀：
  - +：公共（public）；
  - -：私有（private）；
  - #：受保护（protected）。
定义关系类型，常用关系有：
- <|--：继承关系；
- *--：组合关系；
- o--：聚合关系；
- -->：关联关系；
- ..>：依赖关系。
定义关系上的描述文字（可选）：在连接线后面使用冒号加描述文字，如 A --> B : 关联。

另外可以使用 note 关键字为类添加注释。

语法：

```mermaid
classDiagram
    class Student {
        +String name
        +study()
    }

    class Course {
        +String title
    }

    Student --> Course : enrolls
```

效果：

classDiagram
    class Student {
        +String name
        +study()
    }

    class Course {
        +String title
    }

    Student --> Course : enrolls

状态图

要绘制 Mermaid 状态图（State Diagram），需要在开头使用 stateDiagram-v2（推荐）或 stateDiagram 关键字。

然后定义状态和状态之间的转换：

定义状态：直接使用状态名称作为节点，也可以使用 state "显示名称" as 状态标识符 的语法来定义带空格或特殊字符的状态名称；
定义起始和结束状态：使用 [*] 表示起始状态或结束状态；
定义状态转换，常用转换样式有：
- -->：普通转换箭头；
- -->>：虚线转换箭头。
定义转换上的描述文字（可选）：在转换箭头后面使用冒号加描述文字，如 状态A --> 状态B : 触发事件。

另外可以使用 note right of 或 note left of 为状态添加注释，使用 state 块定义复合状态。

语法：

```mermaid
stateDiagram-v2
    [*] --> 待机
    待机 --> 运行中 : 点击开始
    运行中 --> 待机 : 点击停止
```

效果：

stateDiagram-v2
    [*] --> 待机
    待机 --> 运行中 : 点击开始
    运行中 --> 待机 : 点击停止

实体关系图

要绘制 Mermaid 实体关系图（Entity Relationship Diagram），需要在开头使用 erDiagram 关键字。

然后定义实体和它们之间的关系：

定义实体：直接使用实体名称作为节点，在大括号中声明实体的属性，每个属性占一行，格式为 类型属性名；
定义关系类型，常用关系符号有：
- ||--||：一对一强制关系；
- ||--o|：一对零或一关系；
- ||--o{：一对多关系；
- }|--o{：零或一到多关系；
- ||--|{：一对至少一关系。
定义关系上的描述文字（可选）：在连接线后面使用冒号加描述文字，如 USER ||--o{ ORDER : places。

另外可以使用 %% 添加注释。

语法：

```mermaid
erDiagram
    USER {
        int id
        string name
        string email
    }

    ORDER {
        int id
        date created_at
    }

    USER ||--o{ ORDER : places
```

效果：

erDiagram
    USER {
        int id
        string name
        string email
    }

    ORDER {
        int id
        date created_at
    }

    USER ||--o{ ORDER : places

更多 Mermaid 图表类型及语法请参考 Mermaid | Diagramming and charting tool。

徽章

徽章常用于展示项目状态（如构建状态、版本号等）。

徽章的本质其实就是图片而已，所以徽章的重点就在于生成徽章。

常用的徽章生成服务有：

Shields.io（最常用）；
Badgen.net。

以 Shields.io 为例，通过 URL 路径参数来描述徽章信息，最基本的静态徽章的语法，以 https://img.shields.io/badge/ 为 URL 前缀，后跟一个路径，路径由 3 部分组成，使用连字符（-）分隔。

3 个部分分别为：标签、消息和颜色。空格使用下划线符（_）代替。当想要在这 3 各部分之间包含下划线和连字符时，分别使用 __ 和 -- 来代替。

语法：

![Build Status](https://img.shields.io/badge/build-passing-brightgreen)

效果：

Build Status

更多徽章语法请参考对应徽章生成服务的官方文档。

GNU/Linux 指的是将 GNU 项目的软件组件与 Linux 内核结合而成的操作系统。 ↩︎