自定义主题

了解如何自定义 VitePress 主题以匹配你的品牌与设计需求。

主题结构

VitePress 使用可扩展的主题系统，你可以自定义站点的外观与行为。默认主题位于 node_modules/vitepress/dist/client/theme-default/。

创建自定义主题

基础主题结构

创建主题目录结构：

.vitepress/
├── theme/
│  ├── index.ts
│  ├── style.css
│  └── components/
│      └── CustomComponent.vue
└── config.ts

主题入口文件

创建 .vitepress/theme/index.ts：

import { h } from 'vue'
import DefaultTheme from 'vitepress/theme'
import './style.css'

export default {
  ...DefaultTheme,
  Layout: () => {
    return h(DefaultTheme.Layout, null, {
      // 在此处覆盖插槽
    })
  },
  enhanceApp({ app }) {
    // 注册全局组件
    // app.component('MyComponent', MyComponent)
  }
}

自定义样式

将自定义 CSS 写入 .vitepress/theme/style.css：

:root {
  --vp-c-brand: #646cff;
  --vp-c-brand-light: #747bff;
  --vp-c-brand-dark: #535bf2;
}

/* 自定义组件样式 */
.custom-component {
  border: 1px solid var(--vp-c-divider);
  border-radius: 8px;
  padding: 16px;
  margin: 16px 0;
}

主题自定义选项

颜色

通过覆盖 CSS 变量自定义配色方案：

:root {
  /* 品牌主色 */
  --vp-c-brand: #646cff;
  --vp-c-brand-light: #747bff;
  --vp-c-brand-dark: #535bf2;
  
  /* 背景色 */
  --vp-c-bg: #ffffff;
  --vp-c-bg-alt: #f6f6f7;
  
  /* 文本颜色 */
  --vp-c-text-1: #213547;
  --vp-c-text-2: #476582;
  --vp-c-text-3: #8f9198;
}

排版

自定义字体与排版：

:root {
  --vp-font-family-base: 'Inter', -apple-system, BlinkMacSystemFont, sans-serif;
  --vp-font-family-mono: 'Fira Code', 'Monaco', 'Consolas', monospace;
}

/* 自定义标题样式 */
h1 {
  font-size: 2.5rem;
  font-weight: 700;
  line-height: 1.2;
}

布局自定义

覆盖布局组件：

import { h } from 'vue'
import DefaultTheme from 'vitepress/theme'
import CustomLayout from './CustomLayout.vue'

export default {
  ...DefaultTheme,
  Layout: () => h(CustomLayout)
}

高级自定义

自定义组件

创建可复用组件：

<!-- 示例：.vitepress/theme/components/InfoBox.vue -->
<template>
  <div class="info-box" :class="type">
    <div class="icon">{{ icon }}</div>
    <div class="content">
      <h4>{{ title }}</h4>
      <p>{{ content }}</p>
    </div>
  </div>
  </template>

<script setup>
defineProps({
  type: {
    type: String,
    default: 'info'
  },
  title: String,
  content: String,
  icon: String
})
  </script>

<style scoped>
.info-box {
  display: flex;
  padding: 16px;
  border-radius: 8px;
  margin: 16px 0;
}

.info-box.info {
  background: #e3f2fd;
  border: 1px solid #2196f3;
}

.info-box.warning {
  background: #fff3e0;
  border: 1px solid #ff9800;
}
</style>

全局组件

全局注册组件：

// .vitepress/theme/index.ts
import InfoBox from './components/InfoBox.vue'

export default {
  ...DefaultTheme,
  enhanceApp({ app }) {
    app.component('InfoBox', InfoBox)
  }
}

最佳实践

性能

• 保持自定义 CSS 精炼聚焦
• 使用 CSS 变量保证主题一致性
• 避免在主题组件中使用过重的 JavaScript

无障碍

• 保持足够的颜色对比度
• 确保键盘导航可用
• 结合读屏软件进行测试

响应式设计

• 在不同屏幕尺寸上测试
• 使用相对单位（rem、em、%）
• 采用移动优先设计

示例

以下展示在主题中使用自定义组件：

// 在你的 Vue 组件中
<template>
  <div class="custom-info-box">
    <div class="icon">💡</div>
    <div class="content">
      <h4>主题自定义</h4>
      <p>VitePress 主题可高度自定义，并可通过 Vue 组件进行扩展。</p>
    </div>
  </div>
</template>

上述示例展示了如何在 VitePress 主题中集成自定义组件。