Markdown 使用指南

总览 ​

几乎所有的 Markdown 引擎都支持 Markdown 发明者 John Gruber 所设计的 基本语法，但不同的 Markdown 处理引擎在细节表现方面略有不同，下面逐一介绍。

基础标签 ​

兼容绝大部分 Markdown 基础标签!!!

Note ​

默认标题 ​

::: info
一个没啥用的通知
:::

::: tip
这是一个善意的提醒
:::

::: warning
在警告变为错误之前是没人关心的
:::

::: danger
这下你注意到了吧
:::

渲染结果

自定义标题 ​

可以通过在标签的 type 之后附加文本来设置自定义标题。

::: danger STOP
这里的操作很危险，请不要这么做
:::

渲染结果

Tabs ​

在同一块区域切换不同的内容，有些时候确实有用。

注意：Tabs 组件每一项 == 后面的内容 不能重复。

::: tabs

== tab a

a content

== 不要去学

删库跑路 🏃‍♂️

```sh
sudo rm -rf /*
```

:::

渲染结果

imeLine ​

这个世界有两个纬度：时间、事件。

::: timeline 2024-02-29

难得的疯狂星期四，人太多，没吃上。

:::

::: timeline 2024-03-07

现在正在写这个该死的文档

:::

渲染结果

Details ​

折起来的内容真的要打开看吗？

::: details 点我
这是一个折叠的内容
:::

渲染结果

Card ​

一个简单的卡片，没什么特别的

:::card
一些内容
:::

渲染结果

Radio ​

这是个 ... 收音机？

::: radio checked
啊，被选中了
:::

::: radio
咦，我怎么没选中
:::

渲染结果

LinkCard ​

链接还是放在卡片里面好看。

由于 VitePress 的自定义功能有限，因此链接卡片采取自定义组件的方式。

<LinkCard url="https://blog.xkfe.site" />

可配置项 ​

渲染结果

数学公式 ​

主题目前默认支持 MathJax，基于 markdown-it-mathjax3 插件。

行内使用 ​

行内使用 $ 包裹数学公式，例如：

这是平方差公式：$a^2 - b^2 = (a + b)(a - b)$

渲染结果

这是平方差公式：$a^2-b^2=(a+b)(a-b)$

块级使用 ​

块级使用 $$ 包裹数学公式，例如：

这是泰勒公式：

$$
f(x) = f(a) + f'(a)(x-a) + \frac{f''(a)}{2!}(x-a)^2 + \cdots + \frac{f^{(n)}(a)}{n!}(x-a)^n + R_n(x)
$$

渲染结果

这是泰勒公式：

表格中使用 ​

在表格中使用数学公式，需要使用 \( \) 包裹，例如：

| 角度 |              正弦(sin)               |              余弦(cos)               |              正切(tan)               |
| :--: | :----------------------------------: | :----------------------------------: | :----------------------------------: |
|  0°  |          $sin(0^\circ) = 0$          |          $cos(0^\circ) = 1$          |          $tan(0^\circ) = 0$          |
| 30°  |    $sin(30^\circ) = \frac{1}{2}$     | $cos(30^\circ) = \frac{\sqrt{3}}{2}$ | $tan(30^\circ) = \frac{1}{\sqrt{3}}$ |
| 45°  | $sin(45^\circ) = \frac{\sqrt{2}}{2}$ | $cos(45^\circ) = \frac{\sqrt{2}}{2}$ |         $tan(45^\circ) = 1$          |
| 60°  | $sin(60^\circ) = \frac{\sqrt{3}}{2}$ |    $cos(60^\circ) = \frac{1}{2}$     |      $tan(60^\circ) = \sqrt{3}$      |
| 90°  |         $sin(90^\circ) = 1$          |         $cos(90^\circ) = 0$          |  $tan(90^\circ) = \text{undefined}$  |

渲染结果

流程图 ​

流程图及时序图可自行安装对应插件以实现，受限于打包大小，主题将不会内置。

自定义标签 ​

如果上方的各类标签不能满足你的需求，你可以自行添加自定义标签。

标题 ​

要创建标题的话只需使用井号 # 开头，井号的数量对应标题的级别。比如如果你想要创建一个 <h3> 则可以通过用三个 # 开头：### 三级标题。使用井号的标题语法在 CommonMark 规范 中称之为 “ATX 标题”。

标题可选语法 ​

除了使用 ATX 标题外，我们还可以用 Setext 标题：在文本下一行用一个或多个等号 = 表示一级标题，一个或多个短横线 - 表示二级标题。

标题最佳实践 ​

1. 段落之间的 ATX 标题最好使用空行分隔。因为有的 Markdown 引擎不识别缺少前后空行的标题语法。
2. ATX 标题的井号后务必加上一个空格。
3. 尽量不要使用 Setext 语法来写标题，因为 Setext 语法只能写到二级标题。

段落 ​

段落是 Markdown 中最基本的单位，一个 Markdown 文件由一个或多个段落组成。使用空行分隔文本即可。

段落最佳实践 ​

1. 段落开头不要使用空格或者制表符（ \t 即 Tab 键 ）来缩进，否则可能会被当做代码块渲染。
2. 中文传统排版上段落开头有着“空两格”的习惯，可以使用全角空格 　 或者 HTML 实体  。科技领域的文章排版建议不要空两格，段落居左对齐较好。

折行 ​

如果需要文本折行 <br>，可在文本结尾加上两个或更多的空格然后回车。

折行最佳实践 ​

目前大部分 Markdown 引擎会自动将换行符 \n 转换为 <br>，即软换行转硬换行。所以结尾用两个或更多空格的写法虽然稳妥，但是可能也会造成一些小问题：结尾空格在一些编辑器中并不可视；不小心按到或者习惯性按到会造成错误排版。介于这些小问题，可能用 <br> 来折行是最稳妥的做法，但这又不太优雅。另外，在 CommonMark 规范中可以在文本结尾使用反斜杠 \ 来折行，但我也不太推荐这种写法。

综上，我的建议是不要使用结尾空格、\ 或者 <br>，因为现在几乎所有的 Markdown 引擎基本都已经支持软换行转硬换行了。

加粗 ​

要加粗文本，可以使用两个星号 ** 或者两个下划线 __ 包裹待加粗的文本。

加粗最佳实践 ​

加粗用星号和用下划线的不同之处在于星号用法前后可以不加空格，但下划线必须要加。

强调 ​

要强调文本，可以使用一个星号 * 或者一个下划线 _ 包裹待强调的文本。

强调最佳实践 ​

和加粗类似，星号用法前后可以不加空格，但下划线必须要加。

加粗并强调 ​

如果你需要加粗的同时强调文本，可以使用三个星号 *** 或者三个下划线 ___ 包裹待强调的文本。

块引用 ​

要创建块引用 <blockquote> 的话仅需在段落前加上大于号 >。

> 原谅我这一生不羁放纵爱自由，也会怕有一天会跌倒
>
> 背弃了理想 ，谁人都可以
>
> 哪会怕有一天只你共我

渲染结果：

原谅我这一生不羁放纵爱自由，也会怕有一天会跌倒

背弃了理想 ，谁人都可以

哪会怕有一天只你共我

块引用内分段 ​

如果需要分段的话需要可以在分段空行前加上一个 >。

> 今天我， 寒夜里看雪飘过
>
> 怀着冷却了的心窝漂远方
>
> <br/>
>
> 风雨里追赶， 雾里分不清影踪
>
> 天空海阔你与我

渲染结果：

今天我， 寒夜里看雪飘过

怀着冷却了的心窝漂远方

风雨里追赶， 雾里分不清影踪

天空海阔你与我

嵌套块引用 ​

块引用可以嵌套使用，在段落前添加两个大于号 >> 表示两层嵌套。

> 块引用段落
>
> > 嵌套的块引用段落

渲染结果：

块引用段落

嵌套的块引用段落

块引用包含其他元素 ​

块引用能够包含其他大部分语法元素。CommonMark 规范将块引用定义为容器块，容器块可以包含任意块级元素和行级元素，也就是说块引用可以包含其他任意元素。

> ### 标题是叶子块元素
>
> - 列表项一是容器块元素
> - 列表项二也是容器块元素
>
> **加粗**和*强调*是行级元素

渲染结果：

标题是叶子块元素 ​

• 列表项一是容器块元素
• 列表项二也是容器块元素

加粗和强调是行级元素

列表 ​

列表分为有序列表和无序列表。Markdown 中的列表只能包含列表项元素，列表项和块引用一样，都是容器块。也就是说列表项可以包含其他任意元素。

有序列表 ​

有序列表可以通过阿拉伯数字后跟 . 或者 ) 来创建，数字不必递增连续。

1. 有序列表项一
2. 有序列表项二

渲染结果：

1. 有序列表项一
2. 有序列表项二

无序列表 ​

无序列表可以通过短横线 -、星号 * 或者加号 + 来开头，后面需要跟一个空格来分隔文本内容。

- 无序列表项一
- 无序列表项二

渲染结果：

• 无序列表项一
• 无序列表项二

列表项包含其他元素 ​

列表项可以包含其他任意元素，比如段落、块引用、代码块、图片等。使用要点是待包含元素的起始字符要和列表项起始内容“对齐”。

代码 ​

代码可以通过反引号 ` 包裹。

`print("Hello World")`

渲染结果：print("Hello World")

转义反引号 ​

如果你需要显示反引号，可以用转义符 \ 来对反引号进行转义。

代码块 ​

使用围栏代码块语法来排版代码块，即使用 ````` 来包裹代码块，并且指定语法高亮语言：

```html
<html>
  <head> </head>
</html>
```

分隔线 ​

通过大于等于三个星号 ***、短横线 --- 或者下划线 ___ 来创建分隔线。

---
---

---

渲染结果：

超链接 ​

通过 [链接文本](URL) 来创建超链接。

这是 [一家公司](https://www.fuioupay.com/)

渲染结果：

这是 一家公司

添加超链接标题 ​

链接标题是可选的，在圆括号中的 URL 后用双引号包裹。鼠标移到超链接上会浮出显示标题内容。

这是 [一家公司](https://www.fuioupay.com/ "这是一家公司")

渲染结果：

这是 一家公司

URL 和邮件地址 ​

如果要直接显示 URL 或者邮件地址，可以通过 < 和 > 来包裹 URL 或者邮件地址。

<https://www.fuioupay.com/>
<xkfe16@gmail.com>

图片 ​

使用感叹号 ! 后跟超链接就可以渲染图片了。

![vitepress-logo](https://vitepress.dev/vitepress-logo-large.webp)

渲染结果：

vitepress-logo

转义字符 ​

可使用反斜杠 \ 来转义如下字符：

几乎所有 ASCII 标点符号都可以使用反斜杠进行转义。

嵌入 HTML ​

Markdown 天然支持嵌入 HTML 代码。

**Markdown** 和 <em>HTML</em> 混合排版。

渲染结果：

Markdown 和 HTML 混合排版。

嵌入 HTML 最佳实践 ​

这在需要设置图片大小、字体颜色时会比较有用，但我们并不建议过多使用 HTML 来进行排版，一来是因为这样做实际上并不通用，因为有的 Markdown 引擎因为安全原因会过滤部分标签或者属性；二来是因为这样做太不 Markdown 了！

另外，请勿在 HTML 中嵌入 Markdown，这样并不工作：

<p>**粗体**不会生效。</p>

渲染结果：

粗体不会生效。

总结 ​

使用好空行和空格是 Markdown 排版的关键，很多时候就是因为少了个空行或者空格导致产生了非预期的渲染结果。

随着 CommonMark/GFM 规范日趋完善并逐渐成为业界统一的 Markdown 标准，已经有越来越多的 Markdown 引擎实现了该规范。建议 Markdown 使用者尽量该遵循规范来进行排版，这样才能最大程度地避免细节渲染问题。