Markdown 拓展

VitePress 带有内置的 Markdown 拓展。

标题锚点

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

自定义锚点

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

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

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

链接

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

内部链接

内部链接将转换为单页导航的路由链接。此外，子目录中包含的每个 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"：

frontmatter

YAML 格式的 frontmatter 开箱即用：

yaml

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

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

更多信息，参见 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)

输入

[[toc]]

输出

可以使用 markdown.toc 选项配置 TOC 的呈现效果。

自定义容器

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

默认标题

输入

::: 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

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.

自定义标题

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

输入

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

::: details 点我查看代码
```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 class 也可以直接用于元素。样式隔离目前是可选的：

使用喜欢的包管理器来安装需要的依赖项：
sh
```
$ npm add -D postcss
```

创建 docs/.postcssrc.cjs 并将以下内容

import { postcssIsolateStyles } from 'vitepress'

export default {
  plugins: [postcssIsolateStyles()]
}

It uses postcss-prefix-selector under the hood. You can pass its options like this:

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

代码块中的语法高亮

VitePress 使用 Shikiji (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>

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

还可以全局配置中自定义语法高亮主题。有关详细信息，参见 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 hl] 注释实现行高亮。

输入

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

输出

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

代码块中聚焦

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

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

输入

!code 后面只需要一个空格，为了展示原始的代码而不被实际渲染，这里有两个空格：

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

输出

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

代码块中的颜色差异

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

输入

!code 后面只需要一个空格，为了展示原始的代码而不被实际渲染，这里有两个空格。

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

输出

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

高亮“错误”和“警告”

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

输入

!code 后面只需要一个空格，为了展示原始的代码而不被实际渲染，这里有两个空格。

```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 标记来覆盖在配置中的设置。

输入

```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}

Code file

export default function () {
  // ..
}

输出

export default function () {
  // ..
}

TIP

@ 的值对应于源代码根目录，默认情况下是 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#}

<!-- 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.jssnippet with region

export default function () {
  // ..
}

function foo() {
  // ..
}

包含 markdown 文件

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

TIP

也可以使用 @，它的值对应于源代码根目录，默认情况下是 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}

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

输出

When , there are two solutions to and they are

Maxwell's equations:

equation	description
	divergence of is zero
	curl of is proportional to the rate of change of
	wha?

图片懒加载

You can enable lazy loading for each image added via markdown by setting lazyLoading to true in your config file:

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 拓展 ​

标题锚点 ​

自定义锚点 ​

链接 ​

内部链接 ​

页面后缀 ​

外部链接 ​

frontmatter ​

GitHub 风格的表格 ​

Emoji 🎉 ​

目录表 (TOC) ​

自定义容器 ​

默认标题 ​

自定义标题 ​

raw ​

代码块中的语法高亮 ​

在代码块中实现行高亮 ​

代码块中聚焦 ​

代码块中的颜色差异 ​

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

行号 ​

导入代码片段 ​

代码组 ​

包含 markdown 文件 ​

数学方程 ​

图片懒加载 ​

高级配置 ​