主题介绍

VitePress 带有默认主题，并提供许多开箱即用的功能。通过下面列出的导航来了解有关每个功能的更多信息。

如果你没有找到所需的功能，或者您想创建自己的主题，您可以自定义 VitePress 以满足你的要求。在下面，我们将介绍自定义 VitePress 主题的每种方式。

使用自定义主题

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

.
├─ docs
│  ├─ .vitepress
│  │  ├─ theme
│  │  │  └─ index.js
│  │  └─ config.js
│  └─ index.md
└─ package.json

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

interface Theme {
  Layout: Component // Vue 3 component
  NotFound?: Component
  enhanceApp?: (ctx: EnhanceAppContext) => void
  setup?: () => void
}

interface EnhanceAppContext {
  app: App // Vue 3 app instance
  router: Router // VitePress router instance
  siteData: Ref<SiteData>
}

主题入口文件应将主题作为其默认导出：

// .vitepress/theme/index.js
import Layout from './Layout.vue'

export default {
  // root component to wrap each page
  Layout,

  // this is a Vue 3 functional component
  NotFound: () => 'custom 404',

  enhanceApp({ app, router, siteData }) {
    // app is the Vue 3 app instance from `createApp()`.
    // router is VitePress' custom router. `siteData` is
    // a `ref` of current site-level metadata.
  }

  setup() {
    // this function will be executed inside VitePressApp's
    // setup hook. all composition APIs are available here.
  }
}

... Layout 组件会如下所示：

vue

<!-- .vitepress/theme/Layout.vue -->
<template>
  <h1>Custom Layout!</h1>

  <!-- this is where markdown content will be rendered -->
  <Content />
</template>

默认导出是自定义主题的唯一方式。在自定义主题中，它就像普通的 Vite + Vue 3 应用程序一样工作。注意，主题还需要 SSR 兼容。

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

// .vitepress/theme/index.js
import Theme from 'awesome-vitepress-theme'

export default Theme

扩展默认主题

如果你想扩展和自定义默认主题，您可以从 vitepress/theme 导入它并在导出自定义主题中对其进行扩展。以下是一些常见自定义的示例：

注册全局组件

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

export default {
  ...DefaultTheme,
  enhanceApp({ app }) {
    // 注册一个全局组件
    app.component('MyGlobalComponent', /* ... */)
  }
}

由于我们使用 Vite，你还可以利用 Vite 的全局导入特性自动注册组件目录。

自定义 CSS

默认主题 CSS 可通过覆盖根元素的 CSS 变量进行自定义：

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

export default DefaultTheme

css

/* .vitepress/theme/custom.css */
:root {
  --vp-c-brand: #646cff;
  --vp-c-brand-light: #747bff;
}

请参阅可以被覆盖的默认的主题 CSS 变量.

Layout 组件插槽

默认主题 <Layout/> 组件有一些插槽，可用于在页面的某些位置注入内容。这是一个将组件注入到之前的大纲中的示例：

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

export default {
  ...DefaultTheme,
  // override the Layout with a wrapper component that
  // injects the slots
  Layout: MyLayout
}

vue

<!--.vitepress/theme/MyLayout.vue-->
<script setup>
import DefaultTheme from 'vitepress/theme'

const { Layout } = DefaultTheme
</script>

<template>
  <Layout>
    <template #aside-outline-before>
      My custom sidebar top content
    </template>
  </Layout>
</template>

或者你也可以使用渲染函数。

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

export default {
  ...DefaultTheme,
  Layout() {
    return h(DefaultTheme.Layout, null, {
      'aside-outline-before': () => h(MyComponent)
    })
  }
}

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

当通过 frontmatter 开启 layout: 'doc' (default):
- doc-footer-before
- doc-before
- doc-after
- aside-top
- aside-bottom
- aside-outline-before
- aside-outline-after
- aside-ads-before
- aside-ads-after
当通过 frontmatter 开启 layout: 'home':
- home-hero-before
- home-hero-after
- home-features-before
- home-features-after
一定有的:
- layout-top
- layout-bottom
- nav-bar-title-before
- nav-bar-title-after
- nav-bar-content-before
- nav-bar-content-after
- nav-screen-content-before
- nav-screen-content-after

主题介绍 #

使用自定义主题 #

扩展默认主题 #

注册全局组件 #

自定义 CSS #

Layout 组件插槽 #