自定义容器语法

VitePress 提供了丰富的自定义容器语法，用于创建美观的提示框、警告框、代码组等组件。本文档详细介绍各种容器的用法和自定义方法。

基础容器

VitePress 默认支持以下容器类型：

提示容器

::: tip
这是一个提示信息。
:::

::: info
这是一个信息提示。
:::

::: warning
这是一个警告信息。
:::

::: danger
这是一个危险警告。
:::

::: details
这是一个可折叠的详情块。
:::

渲染效果：

TIP

这是一个提示信息。

INFO

这是一个信息提示。

WARNING

这是一个警告信息。

DANGER

这是一个危险警告。

Details

这是一个可折叠的详情块。

自定义标题

可以为容器指定自定义标题：

::: tip 我的提示
这是带自定义标题的提示框。
:::

::: warning 注意
这是带自定义标题的警告框。
:::

::: danger 危险操作
这是带自定义标题的危险警告框。
:::

渲染效果：

我的提示

这是带自定义标题的提示框。

注意

这是带自定义标题的警告框。

危险操作

这是带自定义标题的危险警告框。

代码组容器

基础用法

使用 code-group 容器创建代码标签页：

::: code-group

```npm
npm install vitepress
```

```yarn
yarn add vitepress
```

```pnpm
pnpm add vitepress
```

:::

渲染效果：

npm

npm install vitepress

yarn

yarn add vitepress

pnpm

pnpm add vitepress

带文件名的代码组

::: code-group

```js [config.js]
export default {
  title: 'My Site'
}
```

```ts [config.ts]
import { defineConfig } from 'vitepress'

export default defineConfig({
  title: 'My Site'
})
```

:::

渲染效果：

config.js

export default {
  title: 'My Site'
}

config.ts

import { defineConfig } from 'vitepress'

export default defineConfig({
  title: 'My Site'
})

容器嵌套

容器可以嵌套使用，但需要注意缩进：

::: warning 外层警告
外层内容

  ::: tip 内层提示
  内层内容
  :::
  
外层内容继续
:::

外层警告

外层内容

内层提示

内层内容

外层内容继续 :::

Markdown 在容器内使用

容器内支持完整的 Markdown 语法：

::: tip 容器内的 Markdown
支持 **加粗**、*斜体*、`代码` 等格式。

也支持列表：
- 项目 1
- 项目 2

以及代码块：
```js
console.log('Hello')
```
:::

容器内的 Markdown

支持 加粗、斜体、代码 等格式。

也支持列表：

• 项目 1
• 项目 2

以及代码块：

console.log('Hello')

自定义容器样式

CSS 变量覆盖

可以通过 CSS 变量自定义容器样式：

/* .vitepress/theme/style.css */

/* 提示容器 */
:root {
  --vp-c-tip-1: #42b883;
  --vp-c-tip-2: #42b883;
  --vp-c-tip-soft: rgba(66, 184, 131, 0.14);
}

/* 警告容器 */
:root {
  --vp-c-warning-1: #f6b03a;
  --vp-c-warning-2: #f6b03a;
  --vp-c-warning-soft: rgba(246, 176, 58, 0.14);
}

/* 危险容器 */
:root {
  --vp-c-danger-1: #f56c6c;
  --vp-c-danger-2: #f56c6c;
  --vp-c-danger-soft: rgba(245, 108, 108, 0.14);
}

自定义容器图标

/* 自定义提示容器图标 */
.custom-block.tip .custom-block-title::before {
  content: '💡 ';
}

/* 自定义警告容器图标 */
.custom-block.warning .custom-block-title::before {
  content: '⚠️ ';
}

/* 自定义危险容器图标 */
.custom-block.danger .custom-block-title::before {
  content: '🚫 ';
}

添加自定义容器类型

通过配置可以添加新的容器类型：

// .vitepress/config.mts
import { defineConfig } from 'vitepress'

export default defineConfig({
  markdown: {
    config(md) {
      // 添加自定义容器
      md.use(container, 'question', {
        render: (tokens, idx) => {
          const token = tokens[idx]
          if (token.nesting === 1) {
            return '<div class="custom-block question">\n'
          } else {
            return '</div>\n'
          }
        }
      })
    }
  }
})

然后添加对应样式：

/* 自定义 question 容器样式 */
.custom-block.question {
  border-color: #7c3aed;
  background-color: rgba(124, 58, 237, 0.08);
}

.custom-block.question .custom-block-title {
  color: #7c3aed;
}

.custom-block.question .custom-block-title::before {
  content: '❓ ';
}

使用方式：

::: question 你的问题
这里是问题的详细描述。
:::

常见用例

API 文档中标注状态

::: warning 已废弃
此 API 已在 v2.0 中废弃，请使用 `newMethod()` 替代。
:::

::: info 实验性功能
此功能目前处于实验阶段，API 可能会在未来版本中变更。
:::

::: danger 安全警告
请勿在生产环境中暴露此配置项。
:::

代码示例中的注释

::: details 点击查看完整代码
```js
// 完整的代码示例
export default {
  // 配置项...
}
```
:::

版本差异说明

::: code-group

```v2 [VitePress 2.x]
// 新版本配置
export default {
  title: 'My Site'
}
```

```v1 [VitePress 1.x]
// 旧版本配置
module.exports = {
  title: 'My Site'
}
```

:::

最佳实践

1. 合理选择容器类型

容器	使用场景
tip	有用的提示、技巧、最佳实践
info	一般信息说明
warning	需要注意的事项、潜在问题
danger	严重警告、可能导致数据丢失的操作
details	可选的详细信息、长代码块

2. 保持标题简洁

<!-- 推荐 -->
::: tip 性能优化
使用懒加载可以显著提升页面加载速度。
:::

<!-- 不推荐 -->
::: tip 关于性能优化的一些重要提示和建议
内容过长...
:::

3. 适当使用嵌套

避免过多层级的容器嵌套，通常不超过 2 层。

4. 配合代码块使用

::: tip 示例
以下是一个完整的配置示例：

\`\`\`js
export default {
  title: 'My Site'
}
\`\`\`
:::

相关资源

• Markdown 扩展语法 - 基础 Markdown 语法
• 主题样式定制 - CSS 变量覆盖
• 组件使用 - Vue 组件开发