我的博客

2022年02月23日

Vitepress 是一款静态内容生成器(SSG)，它内置了诸多高效 Markdown 扩展特性，可以大幅提升文档编写体验，所以我选择它构建自己的网络日志。设计风格上参考 Lanyon 主题并做了个性化适配，它非常简约，我很喜欢。

本文梳理了核心特性及实操用法，方便后续复用与查阅。

标题锚点

标题会自动应用锚点，使用 markdown.anchor 选项配置锚点的渲染，也可以直接使用自定义锚点。

# 使用自定义锚点 {#my-anchor}

这允许将标题链接为 #my-anchor，而不是默认的 #使用自定义锚点。

Frontmatter

YAML 格式的 frontmatter 开箱即用：

yaml

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

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

更多信息，参见 frontmatter。

Emoji 🎉

输入

:tada: :100:

输出

🎉 💯

这里可以找到所有支持的 emoji 列表。

目录表 (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.

自定义标题

可以通过在容器的 "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 也可以直接用于元素。样式隔离目前是可选的：

使用喜欢的包管理器来安装需要的依赖项：
sh
```
$ npm add -D postcss
```

创建 docs/postcss.config.mjs 文件并将以下内容添加到其中：

import { postcssIsolateStyles } from 'vitepress'

export default {
  plugins: [postcssIsolateStyles()]
}

你可以像这样传递它的选项：

postcssIsolateStyles({
  includeFiles: [/custom\.css/] // 默认为 [/vp-doc\.css/, /base\.css/]
})

GitHub 风格的警报

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'
  // ...
}

html

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

输入

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

:::

输出

config.jsconfig.ts

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

export default config

import type { UserConfig } from 'vitepress'

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

export default config

图片懒加载

通过在配置文件中将 lazyLoading 设置为 true，可以为通过 markdown 添加的每张图片启用懒加载。

export default {
  markdown: {
    image: {
      // 默认禁用；设置为 true 可为所有图片启用懒加载。
      lazyLoading: true
    }
  }
}

色彩高亮

自动高亮色彩值。

颜色名称

这是 white 和 black 颜色。

十六进制

#fff，#ff0000，#00ff00，#0000ff，#ff000080

颜色函数

rgb(255, 0, 0)，rgba(255, 0, 0, 0.5)，hsl(120, 100%, 50%)，hsla(120, 100%, 50%, 0.5)

现代颜色函数

hwb(60deg 0% 0%)，lab(56.29% -10.96 47.62)，lch(56.29% 62.87 132.5)，oklab(0.63 -0.11 0.14)，oklch(0.63 0.18 132.5)，color(display-p3 1 0 0)

高级配置

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

请查看配置参考：站点配置来获取完整的可配置属性列表。

我的博客

标题锚点 ​

Frontmatter ​

Emoji 🎉 ​

目录表 (TOC) ​

自定义容器 ​

默认标题 ​

自定义标题 ​

raw ​

GitHub 风格的警报 ​

代码块中的语法高亮 ​

在代码块中实现行高亮 ​

代码块中聚焦 ​

代码块中的颜色差异 ​

高亮“错误”和“警告” ​

行号 ​

图片懒加载 ​

色彩高亮 ​

颜色名称 ​

十六进制 ​

颜色函数 ​

现代颜色函数 ​

高级配置 ​