vitepress/docs/zh/guide/markdown.md

Markdown 扩展

VitePress 带有内置的 Markdown 扩展。

标题锚点

标题会自动应用锚点。可以使用 markdown.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"：

• vuejs.org
• VitePress on GitHub

Frontmatter

YAML 格式的 frontmatter 开箱即用：

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

输出

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

自定义标题

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

输入

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

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

输出

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

::: details Click me to view the code

console.log('Hello, VitePress!')

:::

raw

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

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

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

::: details

• 使用你喜欢的包管理器来安装需要的依赖项：

  $ npm install -D postcss postcss-prefix-selector
  

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

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

<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 hl]
    }
  }
}

代码块中聚焦

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

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

输入

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

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

输出

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

代码块中的颜色差异

Adding the // [!code --] or // [!code ++] comments on a line will create a diff of that line, while keeping the colors of the codeblock.

输入

Note that only one space is required after !code, here are two to prevent processing.

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

输出

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

Errors and Warnings in Code Blocks

Adding the // [!code warning] or // [!code error] comments on a line will color it accordingly.

输入

Note that only one space is required after !code, here are two to prevent processing.

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

输出

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

Line Numbers

You can enable line numbers for each code blocks via config:

export default {
  markdown: {
    lineNumbers: true
  }
}

Please see markdown options for more details.

You can add :line-numbers / :no-line-numbers mark in your fenced code blocks to override the value set in config.

输入

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

Import Code Snippets

You can import code snippets from existing files via following syntax:

<<< @/filepath

It also supports line highlighting:

<<< @/filepath{highlightLines}

输入

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

Code file

<<< @/snippets/snippet.js

输出

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

::: tip The value of @ corresponds to the source root. By default it's the VitePress project root, unless srcDir is configured. :::

You can also use a VS Code region to only include the corresponding part of the code file. You can provide a custom region name after a # following the filepath:

输入

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

Code file

<<< @/snippets/snippet-with-region.js

输出

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

You can also specify the language inside the braces ({}) like this:

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

This is helpful if source language cannot be inferred from your file extension.

Code Groups

You can group multiple code blocks like this:

输入

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

:::

输出

::: code-group

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

export default config

import type { UserConfig } from 'vitepress'

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

export default config

:::

You can also import snippets in code groups:

输入

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

:::

输出

::: code-group

<<< @/snippets/snippet.js

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

:::

Markdown File Inclusion

You can include a markdown file in another markdown file like this:

输入

# Docs {#docs}

## Basics {#basics}

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

Part file (parts/basics.md)

Some getting started stuff.

### Configuration {#configuration}

Can be created using `.foorc.json`.

Equivalent code

# Docs {#docs}

## Basics {#basics}

Some getting started stuff.

### Configuration {#configuration}

Can be created using `.foorc.json`.

::: warning Note that this does not throw errors if your file is not present. Hence, when using this feature make sure that the contents are being rendered as expected. :::

Advanced Configuration

VitePress uses markdown-it as the Markdown renderer. A lot of the extensions above are implemented via custom plugins. You can further customize the markdown-it instance using the markdown option in .vitepress/config.js:

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'))
    }
  }
}

See full list of configurable properties in Config Reference: App Config.