Markdown 扩展

VitePress 内置了 Markdown 扩展，下面是详细介绍。

锚链接

VitePress 可以使用 markdown.anchor 选项配置定位点的呈现，支持 标头 和 普通行

标头：允许您链接到标题为 #root-dir 而不是默认的 #项目根目录
普通行：无需标头，也可以快捷设置锚链接

标头普通行

...

项目[根[[toc]]](#root-dir)和[源目录](#source-dir)。

### 项目根目录 {#root-dir}

...

### 项目源目录 {#source-dir}

...

...

项目根目录是 VitePress 尝试查找 [[.vitepress]](#vitepress-dir) 特殊目录的地方。

...

{#vitepress-dir}

.vitepress 目录是 VitePress 配置文件、开发服务器缓存、生成输出和可选主题自定义代码的默认保留位置

链接

VitePress [内部]和[外部]链接都得到了特殊处理。

内部链接

内部链接转换为路由器链路，用于 SPA 导航(侧边导航)。此外，每个子目录中包含的每个 index.md 将自动转换为 index.html ，并带有相应的 URL / 。

例如，给定以下目录结构：

目录结构foo/one.md

txt

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

[Home](/) <!-- 将用户发送到 /index.md -->
[foo](/foo/) <!-- 将用户发送到 foo/index.md -->
[foo heading](./#heading) <!-- 将用户定位到 foo 目录下的文件中的首个 heading 标题 -->
[bar - three](../bar/three) <!-- 定位到 /bar/three.md 推荐写法 -->
[bar - three](../bar/three.md) <!-- 定位到 /bar/three.md 不推荐的写法 -->
[bar - four](../bar/four.html) <!-- 定位到 /bar/four.md 不推荐的写法 -->

页面后缀

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

外部链接

出站链接自动生成 target="_blank" rel="noreferrer"

YAML 前言支持

YAML 前言开箱即用支持：

yaml

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

INFO

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

有关更多详细信息，请参阅配置里的[前言配置]。

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

表情符号

输入

:tada: :100:

输出

🎉 💯

markdown-it-emoji 所有表情符号的列表都可用

自定义容器

自定义容器可以按其类型、标题和内容进行定义。

默认标题

输入：

::: info
这是信息
:::

::: tip
这是提示
:::

::: warning
这是警告
:::

::: danger
这是危险
:::

::: details
这是可折叠区块
:::

输出：

INFO

这是信息

TIP

这是提示

WARNING

这是警告

DANGER

这是危险

Details

这是可折叠区块

自定义标题

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

输入：

::: danger 停止
危险区域，请勿继续
:::

::: details 单击查看代码

```js
console.log('Hello, VitePress!');
```

:::

输出：

停止

危险区域，请勿继续

单击查看代码

console.log('Hello, VitePress!');

代码块中的语法突出显示

简称：语法高亮

VitePress 使用 Shiki 在 Markdown 代码块中突出显示语言语法，使用彩色文本。Shiki 支持多种编程语言。

您需要做的就是将有效的语言别名附加到代码块的开头反引号：

输入输出 js输出 html

txt

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

代码块中的行突出显示

代码块中的行高亮，支持多种指定方式：

单行，例如： {3}
行范围，例如：{5-8}
多条单行，例如：{4,7,9}
行范围和单行组合，例如：{4,7-13,16,23-27,40}

输入输出

txt

```js{4}
export default {
  data () {
    return {
      msg: '高亮行!'
    }
  }
}
```

export default {
  data () {
    return {
      msg: '高亮行!'
    }
  }
}

除了单行之外，还可以指定多个单行/行范围：

输入输出

txt

```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] 注释直接在行中突出显示

输入输出

txt

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

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

聚焦于代码块

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

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

单行聚焦输入单行聚焦输出多行聚焦输入多行聚焦输出

txt

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

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

txt

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

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

代码块中的彩色差异

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

输入输出

txt

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

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

代码块中的错误和警告

在一行上添加 // [!code warning] 或 // [!code error] 注释将相应地为其着色。

输入输出

txt

```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 标记，以覆盖配置中设置的值。

输入禁用行号输出启用行号输出

txt

```ts {1}
// 配置里禁用了行号
const line2 = 'This is line 2'
const line3 = 'This is line 3'
```

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

// 配置里禁用了行号
const line2 = 'This is line 2';
const line3 = 'This is line 3';

// 使用 :line-numbers 启用行号
const line2 = 'This is line 2'
const line3 = 'This is line 3'

导入代码片段

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

原始代码输入输出输出高亮

txt

export default {
  data() {
    return {
      msg1: 'Error', // [!code  error]
      msg2: 'Warning', // [!code  warning]
      msg3: '聚焦', // [!code  focus]
      msg4: '聚焦', // [!code  --]
      msg5: '聚焦', // [!code  ++]
    };
  },
};

<<< @/assets/vitepress/snippets.ts [输出]
<<< @/assets/vitepress/snippets.ts{1,3-5} [输出高亮]

export default {
  data() {
    return {
      msg1: 'Error', 
      msg2: 'Warning', 
      msg3: '聚焦', 
      msg4: '聚焦', 
      msg5: '聚焦', 
    };
  },
};

export default {
  data() {
    return {
      msg1: 'Error', 
      msg2: 'Warning', 
      msg3: '聚焦', 
      msg4: '聚焦', 
      msg5: '聚焦', 
    };
  },
};

提示

@ 的值对应于 [项目源目录]

默认情况下，它跟 VitePress [项目根目录] 一样，除非配置了 srcDir 选项

可以使用 VSCode 区域 功能，仅展示包含代码文件的相应部分

输入文件代码输出

<<< @/assets/vitepress/vscode_region.ts#snippet

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

export default foo;

function foo() {
  // ..
}

可以在大括号 {} 内指定语言，如下所示：

输入

<<< @/assets/vitepress/vscode_region.ts{js}

输出

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

export default foo;

TIP

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

代码分组

在前面我们已经使用了很多这种分组功能：

txt


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

<<< @/assets/vitepress/snippets.ts [源码自带多种功能]
<<< @/assets/vitepress/vscode_region.ts#snippet{1 js:line-numbers} [外部设置功能]

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

export default config;

import type { UserConfig } from 'vitepress';

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

export default config;

export default {
  data() {
    return {
      msg1: 'Error', 
      msg2: 'Warning', 
      msg3: '聚焦', 
      msg4: '聚焦', 
      msg5: '聚焦', 
    };
  },
};

function foo() {
  // ..
}

文件包含

VitePress 可以将 Markdown 文件包含在另一个 Markdown 文件中。

TIP

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

例如，您可以使用以下内容包含相对或绝对的 Markdown 文件：

输入

::: details markdown-it 的表情符号

<!--@include: @/vitepress/emoji.md-->

:::

输出说明

/other/vitepress/emoji.md 文件的内容会全部展示在当前页面

不过由于表情符号内容过多这里就不展示了，大家自己试验下

WARNING

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

数学方程式

要启用它，您需要安装 markdown-it-mathjax3 并在配置文件中将 markdown.math 设置为 true：

安装包配置

bash

pnpm add -D markdown-it-mathjax3

// .vitepress/config.(js|ts|mts)
export default {
    markdown: {
        math: true,
    },
};

案例

输入：

当 $a \ne 0$，有两种解决方案 $(ax^2 + bx + c = 0)$ 和
$$ x = {-b \pm \sqrt{b^2-4ac} \over 2a} $$

**麦克斯韦方程:**

| 方程                                                                                                                                                                      | 描述                                                                                   |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| $\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$	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?

高级配置

VitePress 使用 [markdown-it] 作为 Markdown 渲染器。上面的许多扩展都是通过自定义插件实现的。

您可以使用 markdown-it 中的 markdown 选项进一步自定义 .vitepress/config.js 实例：

import markdownItAnchor from 'markdown-it-anchor';
import markdownItFoo from 'markdown-it-foo';

module.exports = {
    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 扩展 ​

锚链接 ​

链接 ​

内部链接 ​

外部链接 ​

YAML 前言支持 ​

GitHub 样式表 ​

表情符号 ​

目录 ​

自定义容器 ​

默认标题 ​

自定义标题 ​

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

代码块中的行突出显示 ​

聚焦于代码块 ​

代码块中的彩色差异 ​

代码块中的错误和警告 ​

行号 ​

导入代码片段 ​

代码分组 ​

文件包含 ​

数学方程式 ​

案例 ​

高级配置 ​

Markdown 扩展

锚链接

链接

内部链接

外部链接

YAML 前言支持

GitHub 样式表

表情符号

目录

自定义容器

默认标题

自定义标题

代码块中的语法突出显示

代码块中的行突出显示

聚焦于代码块

代码块中的彩色差异

代码块中的错误和警告

行号

导入代码片段

代码分组

文件包含

数学方程式

案例

高级配置