Skip to content

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 文件中:

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 开箱即用:

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

输出

TablesAreCool
col 3 isright-aligned$1600
col 2 iscentered$12
zebra stripesare 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',
  // ...
}
```

输出

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

:::

输出

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

export default config
ts
import type { UserConfig } from 'vitepress'

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

export default config

高级配置

VitePress 使用 markdown-it 作为 Markdown 渲染器。上面提到的很多扩展都是通过自定义插件实现的。你可以使用 .vitepress/config.js 中的 markdown 选项来进一步自定义 markdown-it 实例:

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

查看配置参考:应用配置来获取完整的可配置属性列表。

vitepress开发指南