VitePress 学习指南

主题

主题市场 ​

探索 VitePress 社区主题，快速美化你的站点。

主题选择决策 ​

mermaid
graph TD
    A[选择主题] --> B{站点类型?}
    B -->|文档站| C{是否需要组件演示?}
    B -->|博客| D[博客主题]
    B -->|企业官网| E[企业主题]
    C -->|是| F[vitepress-theme-demoblock]
    C -->|否| G[默认主题扩展]
    D --> H[vitepress-blog-theme]
    E --> I[theme-website]

默认主题 ​

VitePress 内置的默认主题是一个功能完善的文档主题：

特性说明
响应式设计自适应桌面、平板、手机
深色模式自动/手动切换
本地搜索内置搜索功能
多语言i18n 支持
自定义布局CSS 变量覆盖
布局插槽灵活的内容插入点

使用默认主题 ​

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

export default DefaultTheme

默认主题的完整配置请参考 默认主题配置。

社区主题列表 ​

文档主题 ​

主题特点适用场景安装链接
vitepress-theme-demoblock组件在线演示 + 源码展示组件库文档npm i vitepress-theme-demoblock -DGitHub
sphinx-vitepress-themeSphinx 风格文档Python 项目文档npm i sphinx-vitepress-theme -DGitHub
vitepress-theme-apiAPI 文档风格API 参考文档npm i vitepress-theme-api -DGitHub
vitepress-theme-preview组件预览 + 编辑设计系统文档npm i vitepress-theme-preview -DGitHub

博客主题 ​

主题特点适用场景安装链接
vitepress-blog-theme简洁博客，标签/归档/分页个人博客npm i vitepress-blog-theme -DGitHub
vitepress-blog极简博客，Markdown 驱动技术博客npm i vitepress-blog -DGitHub
vitepress-theme-blog多作者博客团队博客npm i vitepress-theme-blog -DGitHub

企业主题 ​

主题特点适用场景安装链接
theme-website企业官网风格产品展示npm i vitepress-theme-website -DGitHub

主题功能对比 ​

特性默认主题demoblockblog-themetheme-apitheme-preview
文档支持✅✅✅✅✅
博客支持❌❌✅❌❌
组件演示❌✅❌❌✅
API 文档❌❌❌✅❌
深色模式✅✅✅✅✅
搜索✅✅✅✅✅
多语言✅⚠️⚠️⚠️⚠️
标签系统❌❌✅❌❌
分页❌❌✅❌❌

使用社区主题 ​

通用安装流程 ​

bash
# 1. 安装主题
npm install theme-name -D

# 2. 配置主题
# 3. 启动开发服务器验证
npm run docs:dev

基本配置 ​

ts
// .vitepress/theme/index.ts
import Theme from 'theme-name'

// 直接使用
export default Theme

// 或扩展主题
export default {
  extends: Theme,
  enhanceApp({ app }) {
    // 自定义配置
  }
}

热门主题配置 ​

vitepress-theme-demoblock ​

专为组件库文档设计，支持组件在线演示：

bash
npm install vitepress-theme-demoblock -D
ts
// .vitepress/config.mts
import { demoblockPlugin } from 'vitepress-theme-demoblock'

export default defineConfig({
  markdown: {
    config(md) {
      md.use(demoblockPlugin)
    }
  }
})
ts
// .vitepress/theme/index.ts
import Theme from 'vitepress-theme-demoblock'

export default Theme

在 Markdown 中使用：

markdown
:::demo 基础用法
\`\`\`vue
<template>
  <button class="my-button">点击我</button>
</template>

<style>
.my-button {
  padding: 8px 16px;
  border: none;
  border-radius: 4px;
  background: #6366f1;
  color: white;
  cursor: pointer;
}
</style>
\`\`\`
:::

vitepress-blog-theme ​

ts
// .vitepress/theme/index.ts
import BlogTheme from 'vitepress-blog-theme'

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

博客文章的 frontmatter：

yaml
---
title: 我的第一篇博客
date: 2026-04-10
tags:
  - VitePress
  - 教程
category: 技术分享
---

扩展默认主题 ​

大多数场景下，扩展默认主题即可满足需求，无需使用社区主题。

自定义样式 ​

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

export default DefaultTheme
css
/* custom.css */
:root {
  --vp-c-brand-1: #6366f1;
  --vp-c-brand-2: #818cf8;
  --vp-c-brand-3: #a5b4fc;
  --vp-c-brand-soft: rgba(99, 102, 241, 0.14);
}

/* 自定义首页 Hero */
.VPHero .name {
  background: linear-gradient(135deg, #6366f1, #8b5cf6);
  -webkit-background-clip: text;
  -webkit-text-fill-color: transparent;
}

添加布局插槽 ​

ts
// .vitepress/theme/index.ts
import DefaultTheme from 'vitepress/theme'
import { h } from 'vue'
import MyFooter from './components/MyFooter.vue'
import ReadingProgress from './components/ReadingProgress.vue'

export default {
  extends: DefaultTheme,
  Layout: () => {
    return h(DefaultTheme.Layout, null, {
      // 页脚前插入自定义组件
      'doc-footer-before': () => h(MyFooter),
      // 阅读进度条
      'layout-top': () => h(ReadingProgress)
    })
  }
}

常用布局插槽 ​

插槽名位置用途
layout-top页面最顶部阅读进度条、公告栏
layout-bottom页面最底部全局页脚
nav-bar-title-before导航栏标题前Logo 图标
nav-bar-title-after导航栏标题后版本号徽章
nav-bar-content-before导航栏内容前搜索框
nav-bar-content-after导航栏内容后主题切换、GitHub 链接
sidebar-nav-before侧边栏导航前搜索
sidebar-nav-after侧边栏导航后广告
home-hero-before首页 Hero 前背景动画
home-hero-after首页 Hero 后数据统计
home-features-before首页特性前补充说明
home-features-after首页特性后赞助商
doc-top文档页顶部面包屑导航
doc-bottom文档页底部版权声明
doc-footer-before页脚前自定义页脚
doc-after文档内容后评论系统
aside-top侧边栏顶部大纲导航
aside-bottom侧边栏底部目录
aside-outline-before大纲前标题
aside-outline-after大纲后回到顶部

详细的扩展方式请参考 自定义布局 和 布局插槽。

主题迁移 ​

从一个主题切换到另一个主题时注意：

迁移检查清单 ​

  1. 配置差异：不同主题的 themeConfig 结构可能不同
  2. Frontmatter：主题特有的 frontmatter 字段需要调整
  3. 组件依赖：主题注册的全局组件可能不可用
  4. 样式冲突：旧主题的样式可能需要清理
  5. 布局插槽：不同主题的插槽名可能不同
  6. 搜索配置：搜索方案的配置方式可能不同

迁移步骤 ​

bash
# 1. 卸载旧主题
npm uninstall old-theme

# 2. 安装新主题
npm install new-theme -D

# 3. 更新主题入口
# 编辑 .vitepress/theme/index.ts

# 4. 清理缓存
rm -rf docs/.vitepress/cache docs/.vitepress/dist

# 5. 启动开发服务器
npm run docs:dev

主题发布 ​

想将自己的主题发布到社区？请参考 主题发布指南。

基本要求 ​

json
// package.json
{
  "name": "vitepress-theme-mine",
  "version": "1.0.0",
  "type": "module",
  "exports": {
    ".": {
      "import": "./dist/index.mjs",
      "require": "./dist/index.cjs"
    },
    "./style.css": "./dist/style.css"
  },
  "files": ["dist"],
  "peerDependencies": {
    "vitepress": ">=1.0.0"
  }
}

发布流程 ​

bash
# 1. 构建主题
npm run build

# 2. 测试主题
npm pack

# 3. 发布到 npm
npm publish

# 4. 提交到 Awesome VitePress
# 在 awesome-vitepress 仓库提交 PR

自定义主题开发 ​

如果你有更复杂的需求，可以开发自定义主题：

最小自定义主题 ​

ts
// .vitepress/theme/index.ts
import { h, defineComponent } from 'vue'
import { useData } from 'vitepress'

const Layout = defineComponent({
  setup() {
    const { frontmatter } = useData()
    return () => h('div', { class: 'custom-layout' }, [
      frontmatter.value.title
        ? h('h1', frontmatter.value.title)
        : null,
      h('content')
    ])
  }
})

export default { Layout }

完整的自定义主题开发指南请参考 自定义主题。

参考链接 ​

📖 相关文章推荐

默认主题配置
主题配置
自定义主题
主题定制
布局插槽
主题插槽

贡献者

加载中...

想要成为贡献者？

在 CNB 上参与贡献

Copyright © 2016 - 2026 VitePress 学习指南