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](/) <!-- 将用户导航至根目录下的 index.html -->
[foo](/foo/) <!-- 将用户导航至目录 foo 下的 index.html -->
[foo heading](./#heading) <!-- 将用户锚定到目录 foo 下的index文件中的一个标题上 -->
[bar - three](../bar/three) <!-- 可以省略扩展名 -->
[bar - three](../bar/three.md) <!-- 可以添加 .md -->
[bar - four](../bar/four.html) <!-- 或者可以添加 .html -->默认情况下，生成的页面和内部链接带有 .html 后缀。
外部链接带有 target="_blank" rel="noreferrer"：
YAML 格式的 frontmatter 开箱即用：
---
title: Blogging Like a Hacker
lang: en-US
---此数据将可用于页面的其余部分，以及所有自定义和主题组件。
更多信息，参见 frontmatter。
输入
| 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:输出
🎉 💯
这里可以找到所有支持的 emoji 列表。
输入
[[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.
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 也可以直接用于元素。样式隔离目前是可选的：
使用喜欢的包管理器来安装需要的依赖项：
$ npm add -D postcss创建 docs/postcss.config.mjs 文件并将以下内容添加到其中：
import { postcssIsolateStyles } from 'vitepress'
export default {
plugins: [postcssIsolateStyles()]
}它在底层使用 postcss-prefix-selector。你可以像这样传递它的选项：
postcssIsolateStyles({
includeFiles: [/vp-doc\\.css/] // 默认为 /base\\.css/
})VitePress 同样支持以标注的方式渲染 GitHub 风格的警报。它们和自定义容器的渲染方式相同。
> [!NOTE]
> 强调用户在快速浏览文档时也不应忽略的重要信息。
> [!TIP]
> 有助于用户更顺利达成目标的建议性信息。
> [!IMPORTANT]
> 对用户达成目标至关重要的信息。
> [!WARNING]
> 因为可能存在风险，所以需要用户立即关注的关键内容。
> [!CAUTION]
> 行为可能带来的负面影响。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'
// ...
}<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 ++] 注释将会为该行创建 diff，同时保留代码块的颜色。
输入
\`\`\`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}
// 默认禁用行号
const line2 = 'This is line 2'
const line3 = 'This is line 3'
\`\`\`
\`\`\`ts:line-numbers {1}
// 启用行号
const line2 = 'This is line 2'
const line3 = 'This is line 3'
\`\`\`
\`\`\`ts:line-numbers=2 {1}
// 行号已启用，并从 2 开始
const line3 = 'This is line 3'
const line4 = 'This is line 4'
\`\`\`输出
// 默认禁用行号
const line2 = 'This is line 2'
const line3 = 'This is line 3'// 启用行号
const line2 = 'This is line 2'
const line3 = 'This is line 3'// 行号已启用，并从 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#}
<!-- 带行高亮: -->
<<< @/snippets/snippet.cs{1,2,4-6 c#}
<!-- 带行号: -->
<<< @/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
\`\`\`
:::输出
/**
* @type {import('vitepress').UserConfig}
*/
const config = {
// ...
}
export default configimport type { UserConfig } from 'vitepress'
const config: UserConfig = {
// ...
}
export default config也可以在代码组中导入代码片段：
输入
::: code-group
<!-- 文件名默认用作标题 -->
<<< @/snippets/snippet.js
<!-- 也可以提供定制的代码组 -->
<<< @/snippets/snippet-with-region.js#snippet{1,2 ts:line-numbers} [snippet with region]
:::输出
export default function () {
// ..
}function foo() {
// ..
}可以像这样在一个 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-mathjax3export 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?_ |输出
`,193)),s("p",null,[a[4]||(a[4]=l("When ")),s("mjx-container",h,[(t(),n("svg",d,a[0]||(a[0]=[i('通过在配置文件中将 lazyLoading 设置为 true，可以为通过 markdown 添加的每张图片启用懒加载。
export default {
markdown: {
image: {
// 默认禁用；设置为 true 可为所有图片启用懒加载。
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: {
// markdown-it-anchor 的选项
// https://github.com/valeriangalliat/markdown-it-anchor#usage
anchor: {
permalink: markdownItAnchor.permalink.headerLink()
},
// @mdit-vue/plugin-toc 的选项
// https://github.com/mdit-vue/mdit-vue/tree/main/packages/plugin-toc#options
toc: { level: [1, 2] },
config: (md) => {
// 使用更多的 Markdown-it 插件！
md.use(markdownItFoo)
}
}
})请查看配置参考：站点配置来获取完整的可配置属性列表。
`,7))])}const j=e(p,[["render",D]]);export{L as __pageData,j as default};