デフォルトテーマの拡張

VitePressのデフォルトテーマはドキュメント用に最適化されており、カスタマイズ可能です。オプションの包括的なリストについては、デフォルトテーマ設定の概要を参照してください。

しかし、設定だけでは不十分なケースがいくつかあります。例えば

1. CSSスタイルを調整する必要がある場合。
2. Vueアプリインスタンスを変更する必要がある場合（例：グローバルコンポーネントの登録）。
3. レイアウトスロットを介してカスタムコンテンツをテーマに挿入する必要がある場合。

これらの高度なカスタマイズには、デフォルトテーマを「拡張」するカスタムテーマを使用する必要があります。

ヒント

先に進む前に、まずカスタムテーマの使用を読んで、カスタムテーマの動作を理解してください。

CSSのカスタマイズ

デフォルトテーマのCSSは、ルートレベルのCSS変数をオーバーライドすることでカスタマイズできます。

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

export default DefaultTheme

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

オーバーライド可能なデフォルトテーマのCSS変数を参照してください。

異なるフォントの使用

VitePressはデフォルトフォントとしてInterを使用しており、ビルド出力にフォントを含めます。フォントは本番環境でも自動的にプリロードされます。ただし、異なるメインフォントを使用したい場合は、これは望ましくない場合があります。

ビルド出力にInterを含めないようにするには、代わりにvitepress/theme-without-fontsからテーマをインポートします。

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

export default DefaultTheme

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

警告

チームページコンポーネントなどのオプションコンポーネントを使用している場合は、vitepress/theme-without-fontsからもインポートしてください！

フォントが@font-faceを介して参照されるローカルファイルである場合、アセットとして処理され、ハッシュされたファイル名で.vitepress/dist/assetsに含まれます。このファイルをプリロードするには、transformHeadビルドフックを使用します。

// .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: ''
          }
        ]
      ]
    }
  }
}

グローバルコンポーネントの登録

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

/** @type {import('vitepress').Theme} */
export default {
  extends: DefaultTheme,
  enhanceApp({ app }) {
    // register your custom global components
    app.component('MyGlobalComponent' /* ... */)
  }
}

TypeScriptを使用している場合

// .vitepress/theme/index.ts
import type { Theme } from 'vitepress'
import DefaultTheme from 'vitepress/theme'

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

Viteを使用しているので、Viteのglobインポート機能を利用して、コンポーネントのディレクトリを自動的に登録することもできます。

レイアウトスロット

デフォルトテーマの<Layout/>コンポーネントには、ページの特定の場所にコンテンツを挿入するために使用できるいくつかのスロットがあります。アウトラインの前にコンポーネントを挿入する例を次に示します。

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

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

<!--.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 { h } from 'vue'
import DefaultTheme from 'vitepress/theme'
import MyComponent from './MyComponent.vue'

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

デフォルトテーマのレイアウトで使用可能なスロットの完全なリスト

• フロントマターで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
• フロントマターでlayout: 'home'が有効になっている場合
  • home-hero-before
  • home-hero-info-before
  • home-hero-info
  • home-hero-info-after
  • home-hero-actions-after
  • home-hero-image
  • home-hero-after
  • home-features-before
  • home-features-after
• フロントマターで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

ビュー遷移APIの使用

外観切り替え時

カラーモードが切り替えられたときにカスタム遷移を提供するために、デフォルトテーマを拡張できます。例

<!-- .vitepress/theme/Layout.vue -->

<script setup lang="ts">
import { useData } from 'vitepress'
import DefaultTheme from 'vitepress/theme'
import { nextTick, provide } from 'vue'

const { isDark } = useData()

const enableTransitions = () =>
  'startViewTransition' in document &&
  window.matchMedia('(prefers-reduced-motion: no-preference)').matches

provide('toggle-appearance', async ({ clientX: x, clientY: y }: MouseEvent) => {
  if (!enableTransitions()) {
    isDark.value = !isDark.value
    return
  }

  const clipPath = [
    `circle(0px at ${x}px ${y}px)`,
    `circle(${Math.hypot(
      Math.max(x, innerWidth - x),
      Math.max(y, innerHeight - y)
    )}px at ${x}px ${y}px)`
  ]

  await document.startViewTransition(async () => {
    isDark.value = !isDark.value
    await nextTick()
  }).ready

  document.documentElement.animate(
    { clipPath: isDark.value ? clipPath.reverse() : clipPath },
    {
      duration: 300,
      easing: 'ease-in',
      pseudoElement: `::view-transition-${isDark.value ? 'old' : 'new'}(root)`
    }
  )
})
</script>

<template>
  <DefaultTheme.Layout />
</template>

<style>
::view-transition-old(root),
::view-transition-new(root) {
  animation: none;
  mix-blend-mode: normal;
}

::view-transition-old(root),
.dark::view-transition-new(root) {
  z-index: 1;
}

::view-transition-new(root),
.dark::view-transition-old(root) {
  z-index: 9999;
}

.VPSwitchAppearance {
  width: 22px !important;
}

.VPSwitchAppearance .check {
  transform: none !important;
}
</style>

結果（**警告！**：点滅する色、急激な動き、明るい光）

デモ

ビュー遷移の詳細については、Chromeドキュメントを参照してください。

ルート変更時

近日公開。

内部コンポーネントのオーバーライド

Viteのエイリアスを使用して、デフォルトテーマコンポーネントをカスタムコンポーネントに置き換えることができます。

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)
          )
        }
      ]
    }
  }
})

コンポーネントの正確な名前を知るには、ソースコードを参照してください。コンポーネントは内部的なものであるため、マイナーリリース間で名前が更新される可能性がわずかにあります。