VitePress 自定义主题

虽然 VitePress 的默认主题功能强大且可配置，但有时你可能需要一个完全独特的设计。VitePress 允许你通过创建一个自定义主题来完全接管站点的 UI。

主题的入口

要使用自定义主题，你需要在 .vitepress 目录下创建一个 theme 目录，并在其中添加一个 index.js 或 index.ts 文件。这个文件是你的自定义主题的入口。

.vitepress
└── theme
    └── index.js

一个最基础的自定义主题配置文件如下：

// .vitepress/theme/index.js
import DefaultTheme from 'vitepress/theme'

export default {
  // 继承默认主题，如果你只想在默认主题基础上进行扩展
  ...DefaultTheme,

  // Layout 是必需的，它将用作每个页面的根组件
  Layout: () => {
    // ... 在这里返回你的自定义布局组件
  }
}

布局组件 (Layout)

Layout 组件是自定义主题的核心。它是一个 Vue 组件，负责渲染页面的整体结构，包括页头、页脚、侧边栏以及最重要的——Markdown 内容。

创建布局文件

在 theme 目录下创建一个 Vue 组件，例如 MyLayout.vue。

.vitepress
└── theme
    ├── index.js
    └── MyLayout.vue

编写布局组件

VitePress 提供了一个特殊的 <Content /> 组件，你必须在你的布局中包含它，它会负责渲染当前页面的 Markdown 内容。

<!-- .vitepress/theme/MyLayout.vue -->
<template>
  <div>
    <header>
      <h1>我的自定义网站</h1>
    </header>
    <main>
      <Content />
    </main>
    <footer>
      <p>版权所有 © 2023</p>
    </footer>
  </div>
</template>

在主题中注册布局

现在，在 index.js 中导入并使用你的布局组件。

// .vitepress/theme/index.js
import DefaultTheme from 'vitepress/theme'
import MyLayout from './MyLayout.vue'

export default {
  ...DefaultTheme, // 继承默认主题的样式和一些底层逻辑
  Layout: MyLayout
}

访问页面数据

在你的自定义布局或任何自定义组件中，你可能需要访问当前页面的数据，例如 frontmatter、标题、路径等。VitePress 提供了 useData 这个 composable 函数来实现这一点。

<!-- .vitepress/theme/MyLayout.vue -->
<script setup>
import { useData } from 'vitepress'

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

<template>
  <div>
    <h1>{{ frontmatter.title }}</h1>
    <p>{{ frontmatter.description }}</p>
    <Content />
  </div>
</template>

添加样式

你可以通过多种方式为你的自定义主题添加样式：

在布局组件中: 直接在 .vue 文件中使用 <style> 标签。

导入 CSS 文件: 在你的 theme/index.js 中直接导入一个 CSS 文件。

// .vitepress/theme/index.js
import DefaultTheme from 'vitepress/theme'
import MyLayout from './MyLayout.vue'
import './custom.css' // 导入自定义样式

export default {
  Layout: MyLayout,
  // ...
}

创建自定义主题提供了极高的自由度，但也意味着你需要自己处理更多的细节，如导航、响应式布局等。对于大多数只想做些许调整的用户来说，扩展默认主题（下一章内容）可能是一个更简单高效的选择。

#VitePress 自定义主题

#主题的入口

#布局组件 (Layout)

#访问页面数据

#添加样式

VitePress 自定义主题

主题的入口

布局组件 (Layout)

访问页面数据

添加样式