VitePress 学习指南

主题

开发自定义主题 ​

从零开始开发一个完整的 VitePress 自定义主题。

主题结构 ​

text
.vitepress/theme/
├── index.ts           # 主题入口
├── Layout.vue         # 主布局
├── components/        # 主题组件
│   ├── NavBar.vue
│   ├── SideBar.vue
│   └── Footer.vue
├── styles/            # 主题样式
│   ├── index.css
│   └── variables.css
└── composables/       # 组合式函数
    └── useTheme.ts

步骤 1：创建主题入口 ​

ts
// .vitepress/theme/index.ts
import Layout from './Layout.vue'
import NotFound from './NotFound.vue'

import './styles/index.css'

export default {
  Layout,
  NotFound,
  enhanceApp({ app }) {
    // 注册全局组件
    // app.component('MyComponent', MyComponent)
  }
}

步骤 2：创建布局组件 ​

vue
<!-- .vitepress/theme/Layout.vue -->
<script setup lang="ts">
import { useData } from 'vitepress'
import NavBar from './components/NavBar.vue'
import SideBar from './components/SideBar.vue'
import Footer from './components/Footer.vue'

const { frontmatter } = useData()
</script>

<template>
  <div class="theme">
    <NavBar />
    
    <div class="layout">
      <SideBar v-if="frontmatter.sidebar !== false" />
      
      <main class="content">
        <Content />
      </main>
    </div>
    
    <Footer />
  </div>
</template>

<style scoped>
.theme {
  min-height: 100vh;
  display: flex;
  flex-direction: column;
}

.layout {
  flex: 1;
  display: flex;
  max-width: 1200px;
  margin: 0 auto;
  width: 100%;
}

.content {
  flex: 1;
  padding: 2rem;
}
</style>

步骤 3：创建导航栏组件 ​

vue
<!-- .vitepress/theme/components/NavBar.vue -->
<script setup lang="ts">
import { useData } from 'vitepress'

const { site, page } = useData()

const nav = [
  { text: '首页', link: '/' },
  { text: '指南', link: '/guide/' },
  { text: 'API', link: '/api/' }
]

const isActive = (link: string) => {
  return page.value.relativePath.startsWith(link.replace('/', ''))
}
</script>

<template>
  <header class="nav-bar">
    <div class="container">
      <a href="/" class="logo">
        <span class="logo-text">{{ site.title }}</span>
      </a>
      
      <nav class="nav-links">
        <a
          v-for="item in nav"
          :key="item.link"
          :href="item.link"
          :class="{ active: isActive(item.link) }"
        >
          {{ item.text }}
        </a>
      </nav>
    </div>
  </header>
</template>

<style scoped>
.nav-bar {
  position: sticky;
  top: 0;
  z-index: 100;
  background: var(--bg-color);
  border-bottom: 1px solid var(--border-color);
}

.container {
  max-width: 1200px;
  margin: 0 auto;
  padding: 0 1.5rem;
  height: 56px;
  display: flex;
  align-items: center;
  justify-content: space-between;
}

.logo {
  font-weight: 600;
  font-size: 1.1rem;
  text-decoration: none;
  color: var(--text-color);
}

.nav-links {
  display: flex;
  gap: 1.5rem;
}

.nav-links a {
  text-decoration: none;
  color: var(--text-color-secondary);
  transition: color 0.2s;
}

.nav-links a:hover,
.nav-links a.active {
  color: var(--brand-color);
}
</style>

步骤 4：创建侧边栏组件 ​

vue
<!-- .vitepress/theme/components/SideBar.vue -->
<script setup lang="ts">
import { useData } from 'vitepress'

const { site, page } = useData()

const sidebar = [
  {
    text: '开始',
    items: [
      { text: '介绍', link: '/guide/' },
      { text: '安装', link: '/guide/installation' }
    ]
  },
  {
    text: '基础',
    items: [
      { text: 'Markdown', link: '/basics/markdown' }
    ]
  }
]

const isActive = (link: string) => {
  return page.value.relativePath === link.replace('/', '') + '.md'
}
</script>

<template>
  <aside class="sidebar">
    <div
      v-for="group in sidebar"
      :key="group.text"
      class="sidebar-group"
    >
      <h4 class="title">{{ group.text }}</h4>
      
      <ul class="items">
        <li v-for="item in group.items" :key="item.link">
          <a
            :href="item.link"
            :class="{ active: isActive(item.link) }"
          >
            {{ item.text }}
          </a>
        </li>
      </ul>
    </div>
  </aside>
</template>

<style scoped>
.sidebar {
  width: 260px;
  padding: 2rem 0;
  border-right: 1px solid var(--border-color);
}

.sidebar-group {
  margin-bottom: 1.5rem;
}

.title {
  padding: 0 1rem;
  font-size: 0.875rem;
  font-weight: 600;
  color: var(--text-color-secondary);
  text-transform: uppercase;
  letter-spacing: 0.05em;
}

.items {
  list-style: none;
  padding: 0.5rem 0 0;
  margin: 0;
}

.items a {
  display: block;
  padding: 0.35rem 1rem;
  color: var(--text-color);
  text-decoration: none;
  font-size: 0.9rem;
  transition: all 0.2s;
}

.items a:hover {
  color: var(--brand-color);
}

.items a.active {
  color: var(--brand-color);
  background: var(--brand-color-soft);
}
</style>

步骤 5：创建页脚组件 ​

vue
<!-- .vitepress/theme/components/Footer.vue -->
<script setup lang="ts">
import { useData } from 'vitepress'

const { site } = useData()
const year = new Date().getFullYear()
</script>

<template>
  <footer class="footer">
    <div class="container">
      <p>© {{ year }} {{ site.title }}. All rights reserved.</p>
    </div>
  </footer>
</template>

<style scoped>
.footer {
  padding: 2rem 0;
  border-top: 1px solid var(--border-color);
  text-align: center;
  color: var(--text-color-secondary);
  font-size: 0.875rem;
}
</style>

步骤 6：创建样式 ​

css
/* .vitepress/theme/styles/variables.css */
:root {
  --bg-color: #ffffff;
  --bg-color-alt: #f6f6f7;
  --text-color: rgba(60, 60, 67);
  --text-color-secondary: rgba(60, 60, 67, 0.78);
  --border-color: #e2e2e3;
  --brand-color: #6366f1;
  --brand-color-soft: rgba(99, 102, 241, 0.14);
}

.dark {
  --bg-color: #1b1b1f;
  --bg-color-alt: #161618;
  --text-color: rgba(255, 255, 245, 0.86);
  --text-color-secondary: rgba(235, 235, 245, 0.6);
  --border-color: #2e2e32;
}
css
/* .vitepress/theme/styles/index.css */
@import './variables.css';

* {
  margin: 0;
  padding: 0;
  box-sizing: border-box;
}

body {
  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, sans-serif;
  background: var(--bg-color);
  color: var(--text-color);
  line-height: 1.6;
}

a {
  color: var(--brand-color);
}

h1, h2, h3, h4, h5, h6 {
  font-weight: 600;
  line-height: 1.3;
}

h1 { font-size: 2rem; margin: 1rem 0; }
h2 { font-size: 1.5rem; margin: 1.5rem 0 1rem; }
h3 { font-size: 1.25rem; margin: 1rem 0; }

p {
  margin: 1rem 0;
}

code {
  background: var(--bg-color-alt);
  padding: 0.2rem 0.4rem;
  border-radius: 4px;
  font-size: 0.9em;
}

pre {
  background: var(--bg-color-alt);
  padding: 1rem;
  border-radius: 8px;
  overflow-x: auto;
}

pre code {
  background: none;
  padding: 0;
}

步骤 7：添加深色模式 ​

vue
<!-- 在 NavBar.vue 中添加 -->
<script setup lang="ts">
import { ref, onMounted } from 'vue'

const isDark = ref(false)

onMounted(() => {
  isDark.value = document.documentElement.classList.contains('dark')
})

const toggleDark = () => {
  isDark.value = !isDark.value
  document.documentElement.classList.toggle('dark', isDark.value)
  localStorage.setItem('theme', isDark.value ? 'dark' : 'light')
}
</script>

<template>
  <!-- 在 nav-links 后添加 -->
  <button class="theme-toggle" @click="toggleDark">
    {{ isDark ? '☀️' : '🌙' }}
  </button>
</template>

<style scoped>
.theme-toggle {
  background: none;
  border: none;
  font-size: 1.25rem;
  cursor: pointer;
}
</style>

学习检查清单 ​

  • [ ] 创建了主题入口文件
  • [ ] 实现了布局组件
  • [ ] 创建了导航栏
  • [ ] 创建了侧边栏
  • [ ] 添加了深色模式支持

下一步 ​

继续学习 主题打包与发布，将你的主题发布到 npm。

📖 相关文章推荐

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

贡献者

加载中...

想要成为贡献者？

在 CNB 上参与贡献

Copyright © 2016 - 2026 VitePress 学习指南