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"：

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:

输出

🎉 💯

所有表情符号列表可用。

自定义容器

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

默认标题

输入

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

自定义标题

您可以通过在容器的"类型"后面附加文本来设置自定义标题。

输入

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

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

输出

STOP

Danger zone, do not proceed

Click me to view the code

console.log('Hello, VitePress!')

`raw`

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

Syntax

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

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

Details

Install required deps with your preferred package manager:
sh
```
$ npm install -D postcss postcss-prefix-selector
```

Create a file named docs/.postcssrc.cjs and add this to it:

module.exports = {
  plugins: {
    'postcss-prefix-selector': {
      prefix: ':not(:where(.vp-raw *))',
      includeFiles: [/vp-doc\.css/],
      transform(prefix, _selector) {
        const [selector, pseudo = ''] = _selector.split(/(:\S*)$/)
        return selector + prefix + pseudo
      }
    }
  }
}

代码块中的语法突出显示

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

输入

注意，!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 标记来覆盖 config.json 中设置的值。

输入

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

输出

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

导入代码片段

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

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

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

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

例如，您可以使用以下命令包含相对 Markdown 文件：

输入

# Docs

## Basics

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

部分文件 (parts/basics.md)

Some getting started stuff.

### 配置

Can be created using `.foorc.json`.

等效代码

# Docs

## Basics

Some getting started stuff.

### 配置

Can be created using `.foorc.json`.

VitePress还支持选择行范围：

输入

# Docs

## Basics

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

部分文件 (parts/basics.md)

Some getting started stuff.

### 配置

Can be created using `.foorc.json`.

等效代码

# Docs

## Basics

### 配置

Can be created using `.foorc.json`.

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

WARNING

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

高级配置

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

const anchor = require('markdown-it-anchor')

module.exports = {
  markdown: {
    // options for markdown-it-anchor
    // https://github.com/valeriangalliat/markdown-it-anchor#usage
    anchor: {
      permalink: anchor.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(require('markdown-it-xxx'))
    }
  }
}

请参阅配置参考：应用程序配置中的可配置属性的完整列表。

Markdown 扩展 ​

标题锚 ​

自定义锚 ​

连接 ​

内部链接 ​

页面后缀 ​

外部链接 ​

Frontmatter ​

GitHub 风格的表格 ​

Emoji 🎉 ​

目录 ​

自定义容器 ​

默认标题 ​

自定义标题 ​

raw ​

代码块中的语法突出显示 ​

代码块中的行突出显示 ​

关注代码块 ​

代码块中的彩色差异 ​

代码块中的错误和警告 ​

行号 ​

导入代码片段 ​

代码组 ​

Markdown 文件包含 ​

高级配置 ​

Markdown 扩展

标题锚

自定义锚

连接

内部链接

页面后缀

外部链接

Frontmatter

GitHub 风格的表格

Emoji 🎉

目录

自定义容器

默认标题

自定义标题

`raw`

代码块中的语法突出显示

代码块中的行突出显示

关注代码块

代码块中的彩色差异

代码块中的错误和警告

行号

导入代码片段

代码组

Markdown 文件包含

高级配置