vitepress-template

Appearance

[[[[Switch to English]]]]

自定义主题 ​

了解如何自定义 VitePress 主题以匹配您的品牌和设计要求。

主题结构 ​

VitePress 使用主题系统，允许您自定义文档站点的外观和行为。默认主题位于 node_modules/vitepress/dist/client/theme-default/。

创建自定义主题 ​

基本主题设置 ​

创建主题目录结构：

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

主题入口点 ​

创建 .vitepress/theme/index.ts：

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

自定义样式 ​

在 .vitepress/theme/style.css 中添加您的自定义 CSS：

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 变量来自定义配色方案：

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

排版 ​

自定义字体和排版：

css
: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;
}

布局自定义 ​

覆盖布局组件：

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

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

高级自定义 ​

自定义组件 ​

创建可重用组件：

vue
<!-- 示例: .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>

全局组件 ​

全局注册组件：

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

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

最佳实践 ​

性能 ​

  • 保持自定义 CSS 最小化且专注
  • 使用 CSS 变量以保持主题一致性
  • 避免在主题组件中使用繁重的 JavaScript

可访问性 ​

  • 保持适当的色彩对比度
  • 确保键盘导航正常工作
  • 使用屏幕阅读器进行测试

响应式设计 ​

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

示例 ​

这是一个在您的主题中使用自定义组件的示例：

js
// 在您的 Vue 组件中
<template>
  <div class="custom-info-box">
    <div class="icon">💡</div>
    <div class="content">
      <h4>主题自定义</h4>
      <p>VitePress 主题高度可定制，可以使用 Vue 组件进行扩展。</p>
    </div>
  </div>
</template>

这演示了如何将自定义组件集成到您的 VitePress 主题中。