Markdown 扩展
VitePress 带有内置的 Markdown 扩展。
标题锚点
标题会自动应用锚点。可以使用 markdown.anchor
选项配置锚点的渲染。
Custom anchors
To specify a custom anchor tag for a heading instead of using the auto-generated one, add a suffix to the heading:
# Using custom anchors {#my-anchor}
# Using custom anchors {#my-anchor}
This allows you to link to the heading as #my-anchor
instead of the default #using-custom-anchors
.
链接
内部和外部链接都会被特殊处理。
内部链接
内部链接将转换为单页导航的路由链接。此外,子目录中包含的每个 index.md
都会自动转换为 index.html
,并带有相应的 URL /
。
例如,给定以下目录结构:
.
├─ index.md
├─ foo
│ ├─ index.md
│ ├─ one.md
│ └─ two.md
└─ bar
├─ index.md
├─ three.md
└─ four.md
.
├─ 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 -->
[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 开箱即用:
---
title: Blogging Like a Hacker
lang: en-US
---
---
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 |
输出
Tables | Are | Cool |
---|---|---|
col 3 is | right-aligned | $1600 |
col 2 is | centered | $12 |
zebra stripes | are neat | $1 |
Emoji 🎉
输入
:tada: :100:
: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.
:::
输出
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
```js
console.log('Hello, VitePress!')
```
:::
输出
STOP
Danger zone, do not proceed
Click me to view the code
console.log('Hello, VitePress!')
console.log('Hello, VitePress!')
raw
这是一个特殊的容器,可以用来防止与 VitePress 的样式和路由冲突。这在记录组件库时特别有用。你可能还想查看 whyframe 以获得更好的隔离。
语法
::: raw
Wraps in a <div class="vp-raw">
:::
::: raw
Wraps in a <div class="vp-raw">
:::
vp-raw
class 也可以直接用于元素。样式隔离目前是可选的:
Details
使用你喜欢的包管理器来安装需要的依赖项:
sh$ npm install -D postcss postcss-prefix-selector
$ npm install -D postcss postcss-prefix-selector
创建
docs/.postcssrc.cjs
并将以下内容jsmodule.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 } } } }
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',
// ...
}
```
```js
export default {
name: 'MyComponent',
// ...
}
```
```html
<ul>
<li v-for="todo in todos" :key="todo.id">
{{ todo.text }}
</li>
</ul>
```
```html
<ul>
<li v-for="todo in todos" :key="todo.id">
{{ todo.text }}
</li>
</ul>
```
输出
export default {
name: 'MyComponent'
// ...
}
export default {
name: 'MyComponent'
// ...
}
<ul>
<li v-for="todo in todos" :key="todo.id">
{{ todo.text }}
</li>
</ul>
<ul>
<li v-for="todo in todos" :key="todo.id">
{{ todo.text }}
</li>
</ul>
在 Shiki 的代码仓库中,可以找到合法的编程语言列表。
还可以全局配置中自定义语法高亮主题。有关详细信息,参见 markdown
选项得到更多信息。
在代码块中实现行高亮
输入
```js{4}
export default {
data () {
return {
msg: 'Highlighted!'
}
}
}
```
```js{4}
export default {
data () {
return {
msg: 'Highlighted!'
}
}
}
```
输出
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'
}
}
}
```
```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',
}
}
}
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]
}
}
}
```
```js
export default {
data () {
return {
msg: 'Highlighted!' // [!code hl]
}
}
}
```
输出
export default {
data() {
return {
msg: 'Highlighted!'
}
}
}
export default {
data() {
return {
msg: 'Highlighted!'
}
}
}
代码块中聚焦
在某一行上添加 // [!code focus]
注释将聚焦它并模糊代码的其他部分。
此外,可以使用 // [!code focus:<lines>]
定义要聚焦的行数。
输入
!code
后面只需要一个空格,为了展示原始的代码而不被实际渲染,这里有两个空格:
```js
export default {
data () {
return {
msg: 'Focused!' // [!code focus]
}
}
}
```
```js
export default {
data () {
return {
msg: 'Focused!' // [!code focus]
}
}
}
```
输出
export default {
data() {
return {
msg: 'Focused!'
}
}
}
export default {
data() {
return {
msg: 'Focused!'
}
}
}
代码块中的颜色差异
在某一行添加 // [!code --]
或 // [!code ++]
注释将会为该行创建 diff,同时保留代码块的颜色。
输入
!code
后面只需要一个空格,为了展示原始的代码而不被实际渲染,这里有两个空格。
```js
export default {
data () {
return {
msg: 'Removed' // [!code --]
msg: 'Added' // [!code ++]
}
}
}
```
```js
export default {
data () {
return {
msg: 'Removed' // [!code --]
msg: 'Added' // [!code ++]
}
}
}
```
输出
export default {
data () {
return {
msg: 'Removed'
msg: 'Added'
}
}
}
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]
}
}
}
```
```js
export default {
data () {
return {
msg: 'Error', // [!code error]
msg: 'Warning' // [!code warning]
}
}
}
```
输出
export default {
data() {
return {
msg: 'Error',
msg: 'Warning'
}
}
}
export default {
data() {
return {
msg: 'Error',
msg: 'Warning'
}
}
}
行号
你可以通过以下配置为每个代码块启用行号:
export default {
markdown: {
lineNumbers: true
}
}
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 {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 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
const line2 = 'This is line 2'
const line3 = 'This is line 3'
导入代码片段
你可以通过下面的语法来从现有文件中导入代码片段:
<<< @/filepath
<<< @/filepath
此语法同时支持行高亮:
<<< @/filepath{highlightLines}
<<< @/filepath{highlightLines}
输入
<<< @/snippets/snippet.js{2}
<<< @/snippets/snippet.js{2}
Code file
export default function () {
// ..
}
export default function () {
// ..
}
输出
export default function () {
// ..
}
export default function () {
// ..
}
TIP
@
的值对应于源代码根目录,默认情况下是 VitePress 项目根目录,除非配置了 srcDir
。或者你也可以从相对路径导入:
<<< ../snippets/snippet.js
<<< ../snippets/snippet.js
你也可以使用 VS Code region 来只包含代码文件的相应部分。你可以在文件目录后面的 #
符号后提供一个自定义的区域名:
输入
<<< @/snippets/snippet-with-region.js#snippet{1}
<<< @/snippets/snippet-with-region.js#snippet{1}
Code file
// #region snippet
function foo() {
// ..
}
// #endregion snippet
export default foo
// #region snippet
function foo() {
// ..
}
// #endregion snippet
export default foo
输出
function 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}
<<< @/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
```
:::
::: 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 config
/**
* @type {import('vitepress').UserConfig}
*/
const config = {
// ...
}
export default config
import type { UserConfig } from 'vitepress'
const config: UserConfig = {
// ...
}
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]
:::
::: 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]
:::
输出
export default function () {
// ..
}
export default function () {
// ..
}
function foo() {
// ..
}
function foo() {
// ..
}
包含 markdown 文件
你可以像这样在一个 markdown 文件中包含另一个 markdown 文件,甚至是内嵌的。
TIP
你也可以使用 @
,它的值对应于源代码根目录,默认情况下是 VitePress 项目根目录,除非配置了 srcDir
。
例如,你可以这样用相对路径包含 Markdown 文件:
输入
# Docs {#docs}
## Basics {#basics}
<!--@include: ./parts/basics.md-->
# Docs {#docs}
## Basics {#basics}
<!--@include: ./parts/basics.md-->
另一个文件 (parts/basics.md
)
Some getting started stuff.
### Configuration {#configuration}
Can be created using `.foorc.json`.
Some getting started stuff.
### Configuration {#configuration}
Can be created using `.foorc.json`.
等价代码
# Docs {#docs}
## Basics {#basics}
Some getting started stuff.
### Configuration {#configuration}
Can be created using `.foorc.json`.
# Docs {#docs}
## Basics {#basics}
Some getting started stuff.
### Configuration {#configuration}
Can be created using `.foorc.json`.
It also supports selecting a line range:
Input
# Docs
## Basics
<!--@include: ./parts/basics.md{3,}-->
# Docs
## Basics
<!--@include: ./parts/basics.md{3,}-->
Part file (parts/basics.md
)
Some getting started stuff.
### Configuration
Can be created using `.foorc.json`.
Some getting started stuff.
### Configuration
Can be created using `.foorc.json`.
Equivalent code
# Docs
## Basics
### Configuration
Can be created using `.foorc.json`.
# Docs
## Basics
### Configuration
Can be created using `.foorc.json`.
The format of the selected line range can be: {3,}
, {,10}
, {1,10}
WARNING
如果你指定的文件不存在,这将不会产生错误。因此,在使用这个功能的时候请保证内容按预期呈现。
高级配置
VitePress 使用 markdown-it 作为 Markdown 渲染器。上面提到的很多拓展功能都是通过自定义插件实现的。你可以使用 .vitepress/config.js
中的 markdown
选项来进一步自定义 markdown-it
实例。
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)
}
}
}
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)
}
}
}
请查看配置参考:站点配置来获取完整的可配置属性列表。