Markdown 扩展
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.md -->
[foo](../../foo/index.md) <!-- 将用户导航至 foo 目录下的 index.md -->
[foo heading](../index.md#heading) <!-- 将用户锚定到 foo index 文件中的一个标题上 -->
[bar - three](../bar/three) <!-- 你可以省略扩展名 -->
[bar - three](../bar/three.md) <!-- 你可以添加 .md -->
[bar - four](../bar/four.html) <!-- 或者你可以添加 .html -->
页面后缀
默认情况下,生成的页面和内部链接带有 .html
后缀。
外部链接
外部链接带有 target="_blank" rel="noreferrer"
:
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]]
输出
可以使用 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.
:::
输出
信息
This is an info box.
提示
This is a tip.
警告
This is a warning.
危险
This is a dangerous warning.
详细信息
This is a details block.
代码块中的语法高亮
VitePress 使用 Shiki 来在 Markdown 代码块中使用彩色文本实现语法高亮。Shiki 支持多种编程语言。需要做的就是将有效的语言别名附加到代码块的开头:
输入
```js
export default {
name: 'MyComponent',
// ...
}
```
输出
export default {
name: 'MyComponent',
// ...
}
代码组
你可以像这样对多个代码块进行分组:
输入
::: 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
import type { UserConfig } from 'vitepress'
const config: UserConfig = {
// ...
}
export default config
高级配置
VitePress 使用 markdown-it 作为 Markdown 渲染器。上面提到的很多扩展都是通过自定义插件实现的。你可以使用 .vitepress/config.js
中的 markdown
选项来进一步自定义 markdown-it
实例:
const anchor = require('markdown-it-anchor')
module.exports = {
markdown: {
// markdown-it-anchor 的选项
// https://github.com/valeriangalliat/markdown-it-anchor#usage
anchor: {
permalink: anchor.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(require('markdown-it-xxx'))
}
}
}
查看配置参考:应用配置来获取完整的可配置属性列表。