Skip to content
当前页导航

扩展默认主题

VitePress 的默认主题针对文档进行了优化,并且可以自定义。请参阅默认主题配置概述 以获取完整的选项列表。

然而,在许多情况下,仅配置是不够的。例如:

1.你需要调整CSS样式; 2.需要修改Vue应用实例,例如注册全局组件; 3. 您需要通过布局槽将自定义内容注入到主题中。

这些高级自定义将需要使用"扩展"默认主题的自定义主题。

TIP

在继续之前,请务必先阅读使用自定义主题 以了解自定义主题的工作原理。

自定义CSS

默认主题 CSS 可以通过覆盖根级 CSS 变量进行自定义:

js
// .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 变量

使用不同的字体

VitePress 使用 Inter 作为默认字体,并将在构建输出中包含该字体。该字体也在生产中自动预加载。但是,如果您想使用不同的主要字体,这可能并不理想。

为了避免在构建输出中包含 Inter,请从 vitepress/theme-without-fonts 导入主题:

js
// .vitepress/theme/index.js
import DefaultTheme from 'vitepress/theme-without-fonts'
import './my-fonts.css'

export default DefaultTheme
css
/* .vitepress/theme/custom.css */
:root {
  --vp-font-family-base: /* normal text font */
  --vp-font-family-mono: /* code font */
}

WARNING

如果您使用团队页面组件等可选组件,请确保也从vitepress/theme-without-fonts导入它们!

如果您的字体是通过@font-face引用的本地文件,它将被作为资源处理并包含在.vitepress/dist/assets下,并带有哈希文件名。要预加载此文件,请使用 transformHead 构建挂钩:

js
// .vitepress/config.js
export default {
  transformHead({ assets }) {
    // adjust the regex accordingly to match your font
    const myFontFile = assets.find(file => /font-name\.\w+\.woff2/)
    if (myFontFile) {
      return [
        [
          'link',
          {
            rel: 'preload',
            href: myFontFile,
            as: 'font',
            type: 'font/woff2',
            crossorigin: ''
          }
        ]
      ]
    }
  }
}

注册全局组件

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

export default {
  extends: DefaultTheme,
  enhanceApp(ctx) {
    // register your custom global components
    ctx.app.component('MyGlobalComponent' /* ... */)
  }
}

由于我们使用的是Vite,您还可以利用Vite的glob导入功能来自动注册组件目录。

布局槽位

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

js
// .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>

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

js
// .vitepress/theme/index.js
import { h } from 'vue'
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' (默认)时:
    • doc-top
    • doc-bottom
    • doc-footer-before
    • doc-before
    • doc-after
    • sidebar-nav-before
    • sidebar-nav-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-info
    • home-hero-image
    • home-hero-after
    • home-features-before
    • home-features-after
  • 当通过 frontmatter 启用 layout: 'page' 时:
    • page-top
    • page-bottom
  • 在未找到 (404) 页面上:
    • not-found
  • 所有布局均可使用:
    • 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

覆盖内部组件

您可以使用 Vite 的 aliases 将默认主题组件替换为您的自定义主题组件:

ts
import { fileURLToPath, URL } from 'node:url'
import { defineConfig } from 'vitepress'

export default defineConfig({
  vite: {
    resolve: {
      alias: [
        {
          find: /^.*\/VPNavBar\.vue$/,
          replacement: fileURLToPath(
            new URL('./components/CustomNavBar.vue', import.meta.url)
          )
        }
      ]
    }
  }
})

要了解组件的确切名称,请参阅我们的源代码。由于这些组件是内部组件,因此它们的名称有可能在次要版本之间更新。

本文档由全栈行动派(qzxdp.cn)翻译并整理