社区主题使用指南

除了 VitePress 默认主题外，社区还提供了丰富的第三方主题，可以快速搭建不同风格的文档站点。本文档介绍常用的社区主题及其使用方法。

版本说明

• 本文档基于 VitePress v1.0.0+ 编写
• 大部分社区主题需要 v1.0.0+ 版本
• 使用前请查看各主题的版本要求和支持环境

为什么使用社区主题？

优势	说明
快速上手	开箱即用的配置，无需从零开始
专业设计	经过社区验证的 UI/UX 设计
持续维护	由社区维护，及时修复问题
功能丰富	内置常用功能，减少开发工作量

推荐社区主题

版本兼容性

主题名称	VitePress 版本	Node.js 版本	状态
vitepress-theme-openapi	v1.0.0+	≥ 16.0.0	活跃维护
vitepress-theme-demoblock	v1.0.0+	≥ 16.0.0	活跃维护
young	v1.0.0+	≥ 16.0.0	活跃维护
vuejs/theme	v1.0.0+	≥ 18.0.0	官方维护

1. vitepress-theme-openapi

专为 API 文档设计的主题，支持 OpenAPI 规范。

特点：

• 自动从 OpenAPI 规范生成文档
• 交互式 API 测试面板
• 请求/响应示例展示
• 支持 OpenAPI 3.0/3.1

安装：

npm install vitepress-theme-openapi

配置：

// .vitepress/config.mts
import { defineConfig } from 'vitepress'
import { theme } from 'vitepress-theme-openapi'

export default defineConfig({
  extends: theme,
  openapi: {
    spec: '/api/openapi.json'
  }
})

适用场景：

• REST API 文档
• OpenAPI/Swagger 规范文档
• 后端服务接口文档

---

2. vitepress-theme-demoblock

组件库文档主题，支持组件演示和代码展示。

特点：

• 组件演示容器
• 代码高亮和复制
• 在线编辑功能
• 自定义演示样式

安装：

npm install vitepress-theme-demoblock -D

配置：

// .vitepress/config.mts
import demoblock from 'vitepress-theme-demoblock'

export default defineConfig({
  markdown: {
    config: (md) => {
      md.use(demoblock)
    }
  }
})

使用：

::: demo 组件演示
\`\`\`vue
<template>
  <button class="my-btn">点击我</button>
</template>

<style>
.my-btn {
  padding: 8px 16px;
  background: #42b883;
  color: white;
  border: none;
  border-radius: 4px;
}
</style>
\`\`\`
:::

适用场景：

• Vue 组件库文档
• UI 设计系统文档
• 前端组件开发文档

---

3. VitePress 博客主题

为博客站点优化的主题模板。

vitepress-blog-theme

特点：

• 文章列表分页
• 标签分类系统
• 归档页面
• 评论系统集成

项目结构：

docs/
├── .vitepress/
│   └── theme/
│       └── index.ts
├── posts/
│   ├── first-post.md
│   └── second-post.md
├── index.md
└── archives.md

young 主题

由 YunYouJun 开发的博客主题。

特点：

• 简洁优雅的设计
• 支持多种布局
• 内置搜索功能
• 支持评论系统

链接： GitHub

---

4. VitePress 主题模板

vuejs/theme

Vue.js 官方文档使用的主题样式。

特点：

• Vue 官方设计风格
• 响应式布局
• 暗色模式支持
• 搜索集成

参考： Vue.js 文档源码

---

如何选择主题？

根据项目类型选择

项目类型	推荐主题
API 文档	vitepress-theme-openapi
组件库	vitepress-theme-demoblock
个人博客	young、自定义博客主题
产品文档	默认主题 + 自定义
技术文档	默认主题 + 扩展

根据定制需求选择

定制程度	建议
无需定制	使用开箱即用的社区主题
轻度定制	社区主题 + CSS 变量覆盖
深度定制	基于默认主题扩展
完全自定义	开发自定义主题

主题开发指南

创建自定义主题

如果现有主题无法满足需求，可以开发自定义主题：

docs/
└── .vitepress/
    └── theme/
        ├── index.ts        # 主题入口
        ├── Layout.vue      # 布局组件
        ├── styles/
        │   └── index.css   # 主题样式
        └── components/     # 主题组件

主题入口：

// .vitepress/theme/index.ts
import Layout from './Layout.vue'
import './styles/index.css'

export default {
  Layout,
  enhanceApp({ app }) {
    // 注册全局组件
  }
}

扩展默认主题

在默认主题基础上进行扩展：

// .vitepress/theme/index.ts
import DefaultTheme from 'vitepress/theme'
import MyLayout from './MyLayout.vue'
import './custom.css'

export default {
  extends: DefaultTheme,
  Layout: MyLayout,
  enhanceApp({ app }) {
    // 添加自定义功能
  }
}

发布主题到 npm

1. 准备项目结构：

my-vitepress-theme/
├── src/
│   ├── index.ts
│   ├── Layout.vue
│   └── styles/
├── package.json
├── README.md
└── tsconfig.json

2. 配置 package.json：

{
  "name": "vitepress-theme-my",
  "version": "1.0.0",
  "type": "module",
  "exports": {
    ".": "./src/index.ts"
  },
  "files": ["src"],
  "peerDependencies": {
    "vitepress": "^1.0.0"
  }
}

3. 发布到 npm：

npm publish

主题常见问题

Q: 如何切换主题？

A: 修改 .vitepress/theme/index.ts 中的导入：

// 使用社区主题
import Theme from 'vitepress-theme-xxx'

// 或使用默认主题
import DefaultTheme from 'vitepress/theme'

Q: 主题和默认配置冲突？

A: 检查主题的配置要求，通常需要在 config.mts 中添加特定配置。

Q: 如何自定义主题样式？

A: 使用 CSS 变量覆盖或添加自定义 CSS 文件：

// .vitepress/theme/index.ts
import Theme from 'vitepress-theme-xxx'
import './custom.css'

export default Theme

Q: 主题更新后样式异常？

A: 检查主题的 CHANGELOG，可能有破坏性变更需要调整配置。

主题推荐列表

主题名称	类型	特点	链接
vitepress-theme-openapi	API 文档	OpenAPI 规范支持	GitHub
vitepress-theme-demoblock	组件文档	组件演示容器	GitHub
young	博客	简洁设计	GitHub
vuejs/theme	官方风格	Vue 官方设计	GitHub

相关资源

• 自定义主题开发 - 主题开发完整教程
• CSS 变量覆盖 - 样式定制方法
• 布局插槽 - 布局扩展技巧
• 学习资源 - 更多主题和工具