Markdown 扩展

VitePress 带有内置的 Markdown 扩展。

标题锚点

标题会自动应用锚点链接。锚点的渲染可以通过 markdown.anchor 选项配置。

自定义锚点

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

# Using custom anchors {#my-anchor}

这允许您将链接到标题作为 #my-anchor 而不是默认的 #using-custom-anchors。

链接

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

内部链接

内部链接被转换为路由链接以进行 SPA 导航。此外，每个子目录中包含的 index.md 将自动转换为 index.html，其对应的 URL 为 /。

例如，给定以下目录结构

.
├─ index.md
├─ foo
│  ├─ index.md
│  ├─ one.md
│  └─ two.md
└─ bar
   ├─ index.md
   ├─ three.md
   └─ four.md

假设您在 foo/one.md 中

[Home](/) <!-- sends the user to the root index.md -->
[foo](/foo/) <!-- sends the user to index.html of directory foo -->
[foo heading](./#heading) <!-- anchors user to a heading in the foo index file -->
[bar - three](../bar/three) <!-- you can omit extension -->
[bar - three](../bar/three.md) <!-- you can append .md -->
[bar - four](../bar/four.html) <!-- or you can append .html -->

页面后缀

页面和内部链接默认情况下会生成 .html 后缀。

外部链接

出站链接会自动获得 target="_blank" rel="noreferrer"

前置信息

YAML 前置信息默认支持

yaml

---
title: Blogging Like a Hacker
lang: en-US
---

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

有关更多详细信息，请参阅前置信息。

GitHub 风格的表格

输入

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

输出

表格	是	酷的
第 3 列是	右对齐	$1600
第 2 列是	居中	$12
斑马条纹	很不错	$1

表情符号 🎉

输入

:tada: :100:

输出

🎉 💯

一个所有表情符号的列表可用。

自定义容器

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

默认标题

输入

::: info
This is an info box.
:::

::: tip
This is a tip.
:::

::: warning
This is a warning.
:::

::: danger
This is a dangerous warning.
:::

::: details
This is a details block.
:::

输出

INFO

这是一个信息框。

TIP

这是一个提示。

WARNING

这是一个警告。

DANGER

这是一个危险警告。

Details

这是一个详细信息块。

自定义标题

您可以在容器的“类型”之后添加文本以设置自定义标题。

输入

::: danger STOP
Danger zone, do not proceed
:::

::: details Click me to view the code
```js
console.log('Hello, VitePress!')
```
:::

输出

STOP

危险区域，请勿继续

点击我查看代码

console.log('Hello, VitePress!')

此外，您可以在站点配置中添加以下内容以全局设置自定义标题，这在非英语写作时很有帮助

// config.ts
export default defineConfig({
  // ...
  markdown: {
    container: {
      tipLabel: '提示',
      warningLabel: '警告',
      dangerLabel: '危险',
      infoLabel: '信息',
      detailsLabel: '详细信息'
    }
  }
  // ...
})

`raw`

这是一个特殊容器，可用于防止与 VitePress 的样式和路由冲突。当您记录组件库时，这尤其有用。您可能还想查看 whyframe 以获得更好的隔离。

语法

::: raw
Wraps in a <div class="vp-raw">
:::

vp-raw 类也可以直接用于元素。样式隔离目前是可选的

使用您喜欢的包管理器安装 postcss
sh
```
$ npm add -D postcss
```

创建一个名为 docs/postcss.config.mjs 的文件，并将以下内容添加到其中

import { postcssIsolateStyles } from 'vitepress'

export default {
  plugins: [postcssIsolateStyles()]
}

它在幕后使用 postcss-prefix-selector。您可以像这样传递其选项

postcssIsolateStyles({
  includeFiles: [/vp-doc\.css/] // defaults to /base\.css/
})

GitHub 风格的警报

VitePress 还支持 GitHub 风格的警报作为提示渲染。它们将与自定义容器一样渲染。

> [!NOTE]
> Highlights information that users should take into account, even when skimming.

> [!TIP]
> Optional information to help a user be more successful.

> [!IMPORTANT]
> Crucial information necessary for users to succeed.

> [!WARNING]
> Critical content demanding immediate user attention due to potential risks.

> [!CAUTION]
> Negative potential consequences of an action.

NOTE

突出显示用户应注意的信息，即使是略读。

TIP

可选信息，帮助用户更成功。

IMPORTANT

用户成功所需的关键信息。

WARNING

由于潜在风险，需要用户立即关注的关键内容。

CAUTION

操作的负面潜在后果。

代码块中的语法高亮

VitePress 使用 Shiki 在 Markdown 代码块中突出显示语言语法，使用彩色文本。Shiki 支持各种编程语言。您需要做的就是在代码块的开头反引号后添加一个有效的语言别名

输入

```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 ++] 注释将创建该行的差异，同时保留代码块的颜色。

输入

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

输出

export default {
  data () {
    return {
      msg: 'Removed'
      msg: 'Added'
    }
  }
}

代码块中的错误和警告

在行上添加 // [!code warning] 或 // [!code error] 注释将相应地对其进行颜色标记。

输入

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

输出

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

行号

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

export default {
  markdown: {
    lineNumbers: true
  }
}

有关更多详细信息，请参阅 markdown 选项。

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

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

输入

```ts {1}
// line-numbers is disabled by default
const line2 = 'This is line 2'
const line3 = 'This is line 3'
```

```ts:line-numbers {1}
// line-numbers is enabled
const line2 = 'This is line 2'
const line3 = 'This is line 3'
```

```ts:line-numbers=2 {1}
// line-numbers is enabled and start from 2
const line3 = 'This is line 3'
const line4 = 'This is line 4'
```

输出

// line-numbers is disabled by default
const line2 = 'This is line 2'
const line3 = 'This is line 3'

// line-numbers is enabled
const line2 = 'This is line 2'
const line3 = 'This is line 3'

// line-numbers is enabled and start from 2
const line3 = 'This is line 3'
const line4 = 'This is line 4'

导入代码片段

您可以通过以下语法从现有文件中导入代码片段

<<< @/filepath

它还支持代码块中的行高亮

<<< @/filepath{highlightLines}

输入

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

代码文件

export default function () {
  // ..
}

输出

export default function () {
  // ..
}

TIP

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

<<< ../snippets/snippet.js

您还可以使用 VS Code 区域仅包含代码文件中的对应部分。您可以在文件路径后的 # 后提供自定义区域名称

输入

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

代码文件

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

export default foo

输出

function foo() {
  // ..
}

您也可以在花括号 ({}) 中指定语言，如下所示

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

<!-- with line highlighting: -->

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

<!-- with line numbers: -->

<<< @/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

<!-- filename is used as title by default -->

<<< @/snippets/snippet.js

<!-- you can provide a custom one too -->

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

:::

输出

snippet.js带区域的代码片段

export default function () {
  // ..
}

function foo() {
  // ..
}

Markdown 文件包含

您可以在另一个 Markdown 文件中包含 Markdown 文件，甚至可以嵌套。

TIP

您也可以在 Markdown 路径前加上 @，它将充当源根目录。默认情况下，它是 VitePress 项目根目录，除非配置了 srcDir。

例如，您可以使用以下方法包含一个相对的 Markdown 文件

输入

# Docs

## Basics

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

部分文件 (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,}-->

部分文件 (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}

WARNING

请注意，如果您的文件不存在，这不会抛出错误。因此，在使用此功能时，请确保内容按预期呈现。

数学方程式

目前，这是可选的。要启用它，您需要安装 markdown-it-mathjax3 并将配置文件中的 markdown.math 设置为 true

npm add -D markdown-it-mathjax3

// .vitepress/config.ts
export default {
  markdown: {
    math: true
  }
}

输入

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?_                                                                                 |

输出

当 $a \neq 0$ ，则 $(a x^{2} + b x + c = 0)$ 的两个解，它们是

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

麦克斯韦方程组

方程	描述
$\nabla \cdot \vec{B} = 0$	$\nabla \times \vec{E} + \frac{1}{c} \frac{\partial \vec{B}}{\partial t} = \vec{0}$	curl of $\vec{E}$ 与 $\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 π ρ$	什么？

图片延迟加载

您可以在配置文件中将 lazyLoading 设置为 true，为通过 markdown 添加的每个图像启用延迟加载。

export default {
  markdown: {
    image: {
      // image lazy loading is disabled by default
      lazyLoading: true
    }
  }
}

高级配置

VitePress 使用 markdown-it 作为 Markdown 渲染器。上面许多扩展都是通过自定义插件实现的。您可以使用 .vitepress/config.js 中的 markdown 选项进一步自定义 markdown-it 实例。

import { defineConfig } from 'vitepress'
import markdownItAnchor from 'markdown-it-anchor'
import markdownItFoo from 'markdown-it-foo'

export default defineConfig({
  markdown: {
    // options for markdown-it-anchor
    // https://github.com/valeriangalliat/markdown-it-anchor#usage
    anchor: {
      permalink: markdownItAnchor.permalink.headerLink()
    },

    // options for @mdit-vue/plugin-toc
    // https://github.com/mdit-vue/mdit-vue/tree/main/packages/plugin-toc#options
    toc: { level: [1, 2] },

    config: (md) => {
      // use more markdown-it plugins!
      md.use(markdownItFoo)
    }
  }
})

查看配置参考：应用程序配置中所有可配置属性的完整列表。

Markdown 扩展 ​

标题锚点 ​

自定义锚点 ​

链接 ​

内部链接 ​

页面后缀 ​

外部链接 ​

前置信息 ​

GitHub 风格的表格 ​

表情符号 🎉 ​

目录 ​

自定义容器 ​

默认标题 ​

自定义标题 ​

raw ​

GitHub 风格的警报 ​

代码块中的语法高亮 ​

代码块中的行高亮 ​

代码块中的焦点 ​

代码块中的彩色差异 ​

代码块中的错误和警告 ​

行号 ​

导入代码片段 ​

代码组 ​

Markdown 文件包含 ​

数学方程式 ​

图片延迟加载 ​

高级配置 ​

Markdown 扩展

标题锚点

自定义锚点

链接

内部链接

页面后缀

外部链接

前置信息

GitHub 风格的表格

表情符号 🎉

目录

自定义容器

默认标题

自定义标题

`raw`

GitHub 风格的警报

代码块中的语法高亮

代码块中的行高亮

代码块中的焦点

代码块中的彩色差异

代码块中的错误和警告

行号

导入代码片段

代码组

Markdown 文件包含

数学方程式

图片延迟加载

高级配置