主题 {#theming}

使用自定义主题 {#using-a-custom-theme}

你可以通过添加 .vitepress/theme/index.js 文件（主题入口文件）来启用自定义主题。

  1. .
  2. ├─ docs
  3. │  ├─ .vitepress
  4. │  │  ├─ theme
  5. │  │  │  └─ index.js
  6. │  │  └─ config.js
  7. │  └─ index.md
  8. └─ package.json

VitePress 自定义主题只是一个包含三个属性的对象，定义如下：

  1. interface Theme {
  2.   Layout: Component // Vue 3 component
  3.   NotFound?: Component
  4.   enhanceApp?: (ctx: EnhanceAppContext) => void
  5. }
  7. interface EnhanceAppContext {
  8.   app: App // Vue 3 app instance
  9.   router: Router // VitePress router instance
  10.   siteData: Ref<SiteData>
  11. }

主题入口文件应该将主题作为它的默认导出：

  1. // .vitepress/theme/index.js
  2. import Layout from './Layout.vue'
  4. export default {
  5.   Layout,
  6.   NotFound: () => 'custom 404', // <- this is a Vue 3 functional component
  7.   enhanceApp({ app, router, siteData }) {
  8.     // app is the Vue 3 app instance from `createApp()`. router is VitePress'
  9.     // custom router. `siteData`` is a `ref`` of current site-level metadata.
  10.   }
  11. }

…其中的 Layout 组件可以像这样：

  1. <!-- .vitepress/theme/Layout.vue -->
  2. <template>
  3.   <h1>Custom Layout!</h1>
  4.   <Content /><!-- this is where markdown content will be rendered -->
  5. </template>

默认导出是定制主题的唯一约定。在你的自定义主题中，它就像一个正常的 Vite + Vue 3 应用程序。请注意，主题也需要是 SSR 兼容。

要使用主题，只需在包入口导出对象。要使用外部主题，请从自定义主题入口导入再重新导出它：

  1. // .vitepress/theme/index.js
  2. import Theme from 'awesome-vitepress-theme'
  3. export default Theme

扩展默认主题 {#extending-the-default-theme}

如果你想扩展和自定义默认主题，你可以从 vitepress/theme 导入它，并在自定义主题入口中扩展它。下面是一些常见的自定义的例子：

注册全局组件 {#registering-global-components}

  1. // .vitepress/theme/index.js
  2. import DefaultTheme from 'vitepress/theme'
  4. export default {
  5.   ...DefaultTheme,
  6.   enhanceApp({ app }) {
  7.     // register global components
  8.     app.component('MyGlobalComponent' /* ... */)
  9.   }
  10. }

由于我们正在使用 Vite，你还可以利用 Vite 的 glob import 特性 来自动注册组件目录。

自定义 CSS {#customizing-css}

默认主题 CSS 是可以通过覆盖根级 CSS 变量来定制的：

  1. // .vitepress/theme/index.js
  2. import DefaultTheme from 'vitepress/theme'
  3. import './custom.css'
  5. export default DefaultTheme
  1. /* .vitepress/theme/custom.css */
  2. :root {
  3.   --c-brand: #646cff;
  4.   --c-brand-light: #747bff;
  5. }

参见可以被重写覆盖的 默认主题 CSS 变量。

布局插槽 {#layout-slots}

默认主题的 <Layout/> 组件有几个插槽，可以用来在页面的特定位置注入内容。下面是一个将组件注入到侧边栏顶部的例子：

  1. // .vitepress/theme/index.js
  2. import DefaultTheme from 'vitepress/theme'
  3. import MyLayout from './MyLayout.vue'
  5. export default {
  6.   ...DefaultTheme,
  7.   // override the Layout with a wrapper component that injects the slots
  8.   Layout: MyLayout
  9. }
  1. <!--.vitepress/theme/MyLayout.vue-->
  2. <script setup>
  3. import DefaultTheme from 'vitepress/theme'
  4. const { Layout } = DefaultTheme
  5. </script>
  7. <template>
  8.   <Layout>
  9.     <template #sidebar-top> My custom sidebar top content </template>
  10.   </Layout>
  11. </template>

默认主题布局中可用的插槽的完整列表：

  • navbar-search
  • sidebar-top
  • sidebar-bottom
  • page-top-ads
  • page-top
  • page-bottom
  • page-bottom-ads
  • 只有当 home: true 通过 frontmatter 启用时可用:
    • home-hero
    • home-features
    • home-footer