Markdown 扩展

7/12/2026 0 字 0 分钟教程 Markdown

VitePress 内置及本博客的 Markdown 扩展。

信息

大部分内容来自 Markdown 扩展 | VitePress，部分扩展功能参考 VuePress Theme Plume。

标题锚点

标题会自动应用锚点。

自定义锚点

要为标题指定自定义锚点而不是使用自动生成的锚点，请向标题添加后缀：

# 自定义锚点 {#my-anchor}

这允许将标题链接为 #my-anchor，而不是默认的 #自定义锚点。

链接

内部和外部链接都会被特殊处理。

内部链接

内部链接将转换为单页导航的路由链接。此外，子目录中包含的每个 index.md 都会自动转换为 index.html，并带有相应的 URL /。支持绝对路径与相对路径。

[首页](/) <!-- 将用户导航至根目录下的 index.html -->

[Markdown 基础](/blog/tutorials/markdown-basic) <!-- 可以省略扩展名 -->

[Markdown 基础](./markdown-basic.md) <!-- 可以添加 .md -->

[Markdown 基础](./markdown-basic.html) <!-- 可以添加 .html -->

渲染为：

首页

Markdown 基础

页面后缀

默认情况下，生成的页面和内部链接带有 .html 后缀。

外部链接

外部链接带有 target="_blank" rel="noreferrer" ：

VitePress

frontmatter

YAML 格式的 frontmatter 开箱即用：

yaml

---
title: Markdown 基础
lang: zh-CN
---

此数据将可用于页面的其余部分，以及所有自定义和主题组件。

更多信息，参见 frontmatter。

Github风格的表格

输入：

| Tables        |      Are      |  Cool |
| ------------- | :-----------: | ----: |
| col 3 is      | right-aligned | $1600 |
| col 2 is      |   centered    |   $12 |
| zebra stripes |   are neat    |    $1 |

输出：

Tables	Are	Cool
col 3 is	right-aligned	$1600
col 2 is	centered	$12
zebra stripes	are neat	$1

Emoji 🎉

输入：

:tada: :100:

输出：

🎉 💯

这里可以找到所有支持的 emoji 列表。

目录表

输入：

[[TOC]]

输出：

自定义容器

自定义容器可以通过它们的类型、标题和内容来定义。

默认标题

输入：

::: note
这是一个注意容器。
:::

::: info
这是一个信息容器。
:::

::: tip
这是一个提示容器。
:::

::: important
这是一个重要容器。
:::

::: warning
这是一个警告容器。
:::

::: caution
这是一个危险容器。
:::

::: danger
这是一个危险容器。
:::

::: details
这是一个详细信息容器。
:::

输出：

注意

这是一个注意容器。

信息

这是一个信息容器。

提示

这是一个提示容器。

重要

这是一个重要容器。

警告

这是一个警告容器。

危险

这是一个危险容器。

危险

这是一个危险容器。

详细信息

这是一个详细信息容器。

自定义标题

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

输入：

::: caution STOP
危险区域，请勿继续
:::

::: details 点我查看代码
```js
console.log('Hello, VitePress!')
```
:::

输出：

STOP

危险区域，请勿继续

点我查看代码

console.log('Hello, VitePress!')

GitHub 风格的警报

VitePress 同样支持以标注的方式渲染 GitHub 风格的警报。它们和自定义容器的渲染方式相同。

输入：

> [!NOTE]
> 强调用户在快速浏览文档时也不应忽略的重要信息。

> [!INFO]
> 用户可能需要的信息。

> [!TIP]
> 有助于用户更顺利达成目标的建议性信息。

> [!IMPORTANT]
> 对用户达成目标至关重要的信息。

> [!WARNING]
> 因为可能存在风险，所以需要用户立即关注的关键内容。

> [!CAUTION]
> 行为可能带来的负面影响。

> [!DANGER]
> 行为可能带来的负面影响。

输出：

注意

强调用户在快速浏览文档时也不应忽略的重要信息。

信息

用户可能需要的信息。

提示

有助于用户更顺利达成目标的建议性信息。

重要

对用户达成目标至关重要的信息。

警告

因为可能存在风险，所以需要用户立即关注的关键内容。

危险

行为可能带来的负面影响。

危险

行为可能带来的负面影响。

代码块中的语法高亮

VitePress 使用 Shiki 在 Markdown 代码块中使用彩色文本实现语法高亮。

输入：

```js
export default {
  name: 'MyComponent',
  // ...
}
```

```html
<ul>
  <li v-for="todo in todos" :key="todo.id">
    {{ todo.text }}
  </li>
</ul>
```

输出：

export default {
  name: 'MyComponent',
  // ...
}

html

<ul>
  <li v-for="todo in todos" :key="todo.id">
    {{ todo.text }}
  </li>
</ul>

在 Shiki 的代码仓库中，可以找到合法的编程语言列表。

还可以在全局配置中自定义语法高亮主题、配置语言别名和自定义语言标签。有关详细信息，参见 markdown 选项得到更多信息。

在代码块中实现行高亮

输入：

```js{4}
export default {
  data () {
    return {
      msg: 'Highlighted!'
    }
  }
}
```

输出：

export default {
  data () {
    return {
      msg: 'Highlighted!'
    }
  }
}

除了单行之外，还可以指定多个单行、多行，或两者均指定：

多行：例如 {5-8}、{3-10}、{10-17}
多个单行：例如 {4,7,9}
多行与单行：例如 {4,7-13,16,23-27,40}

输入：

```js{1,4,6-8}
export default { // Highlighted
  data () {
    return {
      msg: `Highlighted!
      This line isn't highlighted,
      but this and the next 2 are.`,
      motd: 'VitePress is awesome',
      lorem: 'ipsum'
    }
  }
}
```

输出：

export default { // Highlighted
  data () {
    return {
      msg: `Highlighted!
      This line isn't highlighted,
      but this and the next 2 are.`,
      motd: 'VitePress is awesome',
      lorem: 'ipsum'
    }
  }
}

也可以使用 // [!code highlight] 注释实现行高亮。

输入：

```js
export default {
  data () {
    return {
      msg: 'Highlighted!' // [\!code highlight]
    }
  }
}
```

输出：

export default {
  data() {
    return {
      msg: 'Highlighted!'
    }
  }
}

代码块中聚焦

在某一行上添加 // [!code focus] 注释将聚焦它并模糊代码的其他部分。

此外，可以使用 // [!code focus:<lines>] 定义要聚焦的行数。

输入：

```js
export default {
  data () {
    return {
      msg: 'Focused!' // [\!code focus]
    }
  }
}
```

输出：

export default {
  data() {
    return {
      msg: 'Focused!'
    }
  }
}

代码块中的颜色差异

在某一行添加 // [!code --] 或 // [!code ++] 注释将会为该行创建 diff，同时保留代码块的颜色。

输入：

```js
export default {
  data () {
    return {
      remove: 'Removed', // [\!code --]
      add: 'Added' // [\!code ++]
    }
  }
}
```

输出：

export default {
  data() {
    return {
      remove: 'Removed', 
      add: 'Added'
    }
  }
}

高亮“错误”和“警告”

在某一行添加 // [!code warning] 或 // [!code error] 注释将会为该行相应的着色。

输入：

```js
export default {
  data () {
    return {
      error: 'Error', // [\!code error]
      warning: 'Warning' // [\!code warning]
    }
  }
}
```

输出：

export default {
  data() {
    return {
      error: 'Error', 
      warning: 'Warning'
    }
  }
}

行号

可以通过以下配置为每个代码块启用行号：

export default {
  markdown: {
    lineNumbers: true
  }
}

查看 markdown 选项获取更多信息。

可以在代码块中添加 :line-numbers / :no-line-numbers 标记来覆盖在配置中的设置。

还可以通过在 :line-numbers 之后添加 = 来自定义起始行号，例如 :line-numbers=2 表示代码块中的行号从 2 开始。

输入

```ts:no-line-numbers {1}
// 禁用行号
const line2 = 'This is line 2'
const line3 = 'This is line 3'
```

```ts:line-numbers {1}
// 启用行号
const line2 = 'This is line 2'
const line3 = 'This is line 3'
```

```ts:line-numbers=2 {1}
// 行号已启用，并从 2 开始
const line3 = 'This is line 3'
const line4 = 'This is line 4'
```

输出

// 禁用行号
const line2 = 'This is line 2'
const line3 = 'This is line 3'

// 启用行号
const line2 = 'This is line 2'
const line3 = 'This is line 3'

// 行号已启用，并从 2 开始
const line3 = 'This is line 3'
const line4 = 'This is line 4'

代码块中词高亮参考 Plume 实现

输入：

```ts
export function foo() { // [\!code word:Hello]
  const msg = 'Hello World'
  console.log(msg) // prints Hello World
}
```

输出：

export function foo() { 
  const msg = 'Hello World'
  console.log(msg) // prints Hello World
}

你还可以指定高亮显示的次数，例如 [!code word:options:2] 会高亮显示近两个 options。

输入：

```ts
// [\!code word:options:2]
const options = { foo: 'bar' }
options.foo = 'baz'
console.log(options.foo) // 这个不会被高亮显示
```

输出：

const options = { foo: 'bar' }
options.foo = 'baz'
console.log(options.foo) // 这个不会被高亮显示

导入代码片段

可以通过下面的语法来从现有文件中导入代码片段：

<<< @/filepath

此语法同时支持行高亮：

<<< @/filepath{highlightLines}

输入

<<< @/snippets/snippet.js{2}

Code file

export default function () {
  // ..
}

输出

export default function () { 
  // ..
}

提示

@ 的值对应于源代码根目录，默认情况下是 VitePress 项目根目录，除非配置了 srcDir。或者也可以从相对路径导入：

<<< ../snippets/snippet.js

也可以使用 VS Code region 来只包含代码文件的相应部分。可以在文件目录后面的 # 符号后提供一个自定义的区域名：

输入

<<< @/snippets/snippet-with-region.js#snippet{1}

Code file

// #region snippet
function foo() {
  // ..
}
// #endregion snippet

export default foo

输出

function foo() { 
  // ..
}

也可以像这样在大括号内({})指定语言：

<<< @/snippets/snippet.cs{c#}

<!-- 带行高亮: -->

<<< @/snippets/snippet.cs{1,2,4-6 c#}

<!-- 带行号: -->

<<< @/snippets/snippet.cs{1,2,4-6 c#:line-numbers}

如果无法从文件扩展名推测出源语言，这将会很有帮助

代码组

可以像这样对多个代码块进行分组：

输入

::: code-group

```js [config.js]
/**
 * @type {import('vitepress').UserConfig}
 */
const config = {
  // ...
}

export default config
```

```ts [config.ts]
import type { UserConfig } from 'vitepress'

const config: UserConfig = {
  // ...
}

export default config
```

:::

输出

config.jsconfig.ts

/**
 * @type {import('vitepress').UserConfig}
 */
const config = {
  // ...
}

export default config

import type { UserConfig } from 'vitepress'

const config: UserConfig = {
  // ...
}

export default config

也可以在代码组中导入代码片段：

输入

::: code-group

<!-- 文件名默认用作标题 -->

<<< @/snippets/snippet.js

<!-- 也可以提供定制的代码组 -->

<<< @/snippets/snippet-with-region.js#snippet{1,2 ts:line-numbers} [snippet with region]

:::

输出

snippet.jssnippet with region

export default function () {
  // ..
}

function foo() {
  // ..
}

包含 markdown 文件

可以像这样在一个 markdown 文件中包含另一个 markdown 文件，甚至是内嵌的。

提示

也可以使用 @，它的值对应于源代码根目录，默认情况下是 VitePress 项目根目录，除非配置了 srcDir。

例如，可以这样用相对路径包含 Markdown 文件：

输入

# Docs

## Basics

<!--@@include: ./parts/basics.md-->

Part file (parts/basics.md)

Some getting started stuff.

### Configuration

Can be created using `.foorc.json`.

等价代码

# Docs

## Basics

Some getting started stuff.

### Configuration

Can be created using `.foorc.json`.

它还支持选择行范围：

输入

# Docs

## Basics

<!--@@include: ./parts/basics.md{3,}-->

Part file (parts/basics.md)

Some getting started stuff.

### Configuration

Can be created using `.foorc.json`.

等价代码

# Docs

## Basics

### Configuration

Can be created using `.foorc.json`.

所选行范围的格式可以是： {3,}、 {,10}、{1,10}

警告

如果指定的文件不存在，这将不会产生错误。因此，在使用这个功能的时候请保证内容按预期呈现。

数学方程

输入：

When $a \ne 0$, there are two solutions to $(ax^2 + bx + c = 0)$ and they are
$$ x = {-b \pm \sqrt{b^2-4ac} \over 2a} $$

**Maxwell's equations:**

| equation                                                                                                                                                                  | description                                                                            |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| $\nabla \cdot \vec{\mathbf{B}}  = 0$                                                                                                                                      | divergence of $\vec{\mathbf{B}}$ is zero                                               |
| $\nabla \times \vec{\mathbf{E}}\, +\, \frac1c\, \frac{\partial\vec{\mathbf{B}}}{\partial t}  = \vec{\mathbf{0}}$                                                          | curl of $\vec{\mathbf{E}}$ is proportional to the rate of change of $\vec{\mathbf{B}}$ |
| $\nabla \times \vec{\mathbf{B}} -\, \frac1c\, \frac{\partial\vec{\mathbf{E}}}{\partial t} = \frac{4\pi}{c}\vec{\mathbf{j}}    \nabla \cdot \vec{\mathbf{E}} = 4 \pi \rho$ | _wha?_                                                                                 |

输出：

When $a \neq 0$ , there are two solutions to $(a x^{2} + b x + c = 0)$ and they are

x = \frac{- b \pm \sqrt{b^{2} - 4 a c}}{2 a}

Maxwell's equations:

equation	description
$\nabla \cdot \vec{B} = 0$	divergence of $\vec{B}$ is zero
$\nabla \times \vec{E} + \frac{1}{c} \frac{\partial \vec{B}}{\partial t} = \vec{0}$	curl of $\vec{E}$ is proportional to the rate of change of $\vec{B}$
$\nabla \times \vec{B} - \frac{1}{c} \frac{\partial \vec{E}}{\partial t} = \frac{4 π}{c} \vec{j} \nabla \cdot \vec{E} = 4 π ρ$	wha?

马克笔参考 Plume 实现

使用 == == 进行标记。

==Default== - Default

内置了以下的配置方案：

==Info=={.info} - Info
==Note=={.note} - Note
==Tip=={.tip} - Tip
==Warning=={.warning} - Warning
==Danger=={.danger} - Danger
==Caution=={.caution} - Caution
==Important=={.important} - Important

隐秘文本参考 Plume 实现

输入：

!!需要隐秘的内容!!

输出：

需要隐秘的内容

上下角标参考 Plume 实现

使用 ^ ^ 进行上角标标注。
使用 ~ ~ 进行下角标标注。

输入：

- 19^th^
- H~2~O

输出：

19^th
H₂O

属性支持

你可以使用特殊标记为 Markdown 元素添加属性。

为图片添加属性：

这将为图片添加一个名为 full-width 的 class 属性，以及一个 width 属性，值为 100%。

![](/avatar.png){.full-width width="100%"}

同时也支持其他属性:

一个包含文字的段落。 {#p .a .b align=center customize-attr="content with spaces"}

这将被渲染为：

html

<p id="p" class="a b" align="center" customize-attr="content with spaces">
  一个包含文字的段落。
</p>

提示

链接后面添加 {.readmore} 可以显示为特殊样式：参考 Plume 样式

输入：

[更多信息请阅读 **VitePress** 文档](https://vitepress.dev/zh/){.readmore}

输出：

更多信息请阅读 VitePress 文档

任务列表

输入：

- [ ] 任务 1
- [x] 任务 2
- [ ] 任务 3

输出：

任务 1
任务 2
任务 3

贡献者

Jursin

页面历史

最后编辑于 6 天前

查看完整历史

Markdown 扩展

标题锚点

自定义锚点

链接

内部链接

页面后缀

外部链接

frontmatter

Github风格的表格

Emoji 🎉

目录表

自定义容器

默认标题

自定义标题

GitHub 风格的警报

代码块中的语法高亮

在代码块中实现行高亮

代码块中聚焦

代码块中的颜色差异

高亮“错误”和“警告”

行号

代码块中词高亮参考 Plume 实现

导入代码片段

代码组

包含 markdown 文件

数学方程

马克笔参考 Plume 实现

隐秘文本参考 Plume 实现

上下角标参考 Plume 实现

属性支持

任务列表

贡献者

页面历史

评论区

Preview:

Markdown 扩展

标题锚点 ​

自定义锚点 ​

链接 ​

内部链接 ​

页面后缀 ​

外部链接 ​

frontmatter ​

Github风格的表格 ​

Emoji 🎉 ​

目录表 ​

自定义容器 ​

默认标题 ​

自定义标题 ​

GitHub 风格的警报 ​

代码块中的语法高亮 ​

在代码块中实现行高亮 ​

代码块中聚焦 ​

代码块中的颜色差异 ​

高亮“错误”和“警告” ​

行号 ​

代码块中词高亮 参考 Plume 实现 ​

导入代码片段 ​

代码组 ​

包含 markdown 文件 ​

数学方程 ​

马克笔 参考 Plume 实现 ​

隐秘文本 参考 Plume 实现 ​

上下角标 参考 Plume 实现 ​

属性支持 ​

任务列表 ​

贡献者

页面历史

评论区

Preview:

标题锚点

自定义锚点

链接

内部链接

页面后缀

外部链接

frontmatter

Github风格的表格

Emoji 🎉

目录表

自定义容器

默认标题

自定义标题

GitHub 风格的警报

代码块中的语法高亮

在代码块中实现行高亮

代码块中聚焦

代码块中的颜色差异

高亮“错误”和“警告”

行号

代码块中词高亮参考 Plume 实现

导入代码片段

代码组

包含 markdown 文件

数学方程

马克笔参考 Plume 实现

隐秘文本参考 Plume 实现

上下角标参考 Plume 实现

属性支持

任务列表