サイト設定

サイト設定では、サイト全体のグローバル設定を定義します。アプリ設定オプションは、使用するテーマに関係なく、すべての VitePress サイトに適用されます。たとえば、ベースディレクトリやサイトのタイトルなどです。

概要

設定ファイルの解決

設定ファイルは常に <root>/.vitepress/config.[ext] から解決されます。<root> は VitePress のプロジェクトルートで、[ext] にはサポートされる拡張子が入ります。TypeScript はそのまま使えます。サポートされる拡張子は .js、.ts、.mjs、.mts です。

設定ファイルでは ES Modules 構文の使用を推奨します。設定オブジェクトをデフォルトエクスポートしてください。

export default {
  // アプリレベルの設定
  lang: 'en-US',
  title: 'VitePress',
  description: 'Vite & Vue powered static site generator.',
  ...
}

動的（非同期）設定

設定を動的に生成する必要がある場合は、関数をデフォルトエクスポートすることもできます。例:

import { defineConfig } from 'vitepress'

export default async () => {
  const posts = await (await fetch('https://my-cms.com/blog-posts')).json()

  return defineConfig({
    // アプリレベル設定
    lang: 'en-US',
    title: 'VitePress',
    description: 'Vite & Vue powered static site generator.',

    // テーマレベル設定
    themeConfig: {
      sidebar: [
        ...posts.map((post) => ({
          text: post.name,
          link: `/posts/${post.name}`
        }))
      ]
    }
  })
}

トップレベル await も使用できます。例:

import { defineConfig } from 'vitepress'

const posts = await (await fetch('https://my-cms.com/blog-posts')).json()

export default defineConfig({
  // アプリレベル設定
  lang: 'en-US',
  title: 'VitePress',
  description: 'Vite & Vue powered static site generator.',

  // テーマレベル設定
  themeConfig: {
    sidebar: [
      ...posts.map((post) => ({
        text: post.name,
        link: `/posts/${post.name}`
      }))
    ]
  }
})

設定のインテリセンス

defineConfig ヘルパーを使うと、TypeScript による補完が効きます。対応 IDE であれば、JavaScript と TypeScript のどちらでも動作します。

import { defineConfig } from 'vitepress'

export default defineConfig({
  // ...
})

型付きのテーマ設定

デフォルトでは、defineConfig はデフォルトテーマのテーマ設定型を想定します。

import { defineConfig } from 'vitepress'

export default defineConfig({
  themeConfig: {
    // 型は `DefaultTheme.Config`
  }
})

カスタムテーマを使用しており、そのテーマ設定に型チェックを効かせたい場合は、代わりに defineConfigWithTheme を使い、ジェネリクスでカスタムテーマの設定型を渡してください。

import { defineConfigWithTheme } from 'vitepress'
import type { ThemeConfig } from 'your-theme'

export default defineConfigWithTheme<ThemeConfig>({
  themeConfig: {
    // 型は `ThemeConfig`
  }
})

Vite・Vue・Markdown の設定

Vite
Vite の設定は VitePress 設定の vite オプションで行えます。別途 Vite の設定ファイルを作る必要はありません。
Vue
VitePress には公式の Vue プラグイン（@vitejs/plugin-vue）が同梱されています。オプションは VitePress 設定の vue から指定できます。
Markdown
既定の Markdown-It インスタンスは、VitePress 設定の markdown オプションでカスタマイズできます。

サイトメタデータ

title

型: string
既定値: VitePress
ページ単位での上書き: frontmatter

サイトのタイトル。デフォルトテーマではナビバーに表示されます。

titleTemplate を定義していない場合、個々のページタイトルの既定のサフィックスとしても使われます。各ページの最終タイトルは、そのページの最初の <h1> 見出しのテキストに、グローバルの title をサフィックスとして結合したものになります。次の設定とページ内容の例:

export default {
  title: 'My Awesome Site'
}

# Hello

このページのタイトルは Hello | My Awesome Site になります。

titleTemplate

型: string | boolean
ページ単位での上書き: frontmatter

各ページタイトルのサフィックス、またはタイトル全体のカスタマイズができます。例:

export default {
  title: 'My Awesome Site',
  titleTemplate: 'Custom Suffix'
}

# Hello

このページのタイトルは Hello | Custom Suffix になります。

タイトルの描画方法を完全にカスタマイズするには、titleTemplate 内で :title シンボルを使います。

export default {
  titleTemplate: ':title - Custom Suffix'
}

ここで :title はページ先頭の <h1> から推論されたテキストに置き換えられます。先ほどの例では Hello - Custom Suffix になります。

false を設定するとタイトルのサフィックスを無効にできます。

description

型: string
既定値: A VitePress site
ページ単位での上書き: frontmatter

サイトの説明。ページの HTML に <meta> タグとして出力されます。

export default {
  description: 'A VitePress site'
}

head

型: HeadConfig[]
既定値: []
ページ単位での追加: frontmatter

ページ HTML の <head> に追加で出力する要素。ユーザーが追加したタグは、VitePress のタグの後、</head> の直前にレンダリングされます。

type HeadConfig =
  | [string, Record<string, string>]
  | [string, Record<string, string>, string]

例: favicon を追加

export default {
  head: [['link', { rel: 'icon', href: '/favicon.ico' }]]
} // favicon.ico は public に配置。base を設定している場合は /base/favicon.ico を利用

/* 出力結果:
  <link rel="icon" href="/favicon.ico">
*/

例: Google Fonts を追加

export default {
  head: [
    [
      'link',
      { rel: 'preconnect', href: 'https://fonts.googleapis.com' }
    ],
    [
      'link',
      { rel: 'preconnect', href: 'https://fonts.gstatic.com', crossorigin: '' }
    ],
    [
      'link',
      { href: 'https://fonts.googleapis.com/css2?family=Roboto&display=swap', rel: 'stylesheet' }
    ]
  ]
}

/* 出力結果:
  <link rel="preconnect" href="https://fonts.googleapis.com">
  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
  <link href="https://fonts.googleapis.com/css2?family=Roboto&display=swap" rel="stylesheet">
*/

例: Service Worker を登録

export default {
  head: [
    [
      'script',
      { id: 'register-sw' },
      `;(() => {
        if ('serviceWorker' in navigator) {
          navigator.serviceWorker.register('/sw.js')
        }
      })()`
    ]
  ]
}

/* 出力結果:
  <script id="register-sw">
    ;(() => {
      if ('serviceWorker' in navigator) {
        navigator.serviceWorker.register('/sw.js')
      }
    })()
  </script>
*/

例: Google Analytics を使用

export default {
  head: [
    [
      'script',
      { async: '', src: 'https://www.googletagmanager.com/gtag/js?id=TAG_ID' }
    ],
    [
      'script',
      {},
      `window.dataLayer = window.dataLayer || [];
      function gtag(){dataLayer.push(arguments);}
      gtag('js', new Date());
      gtag('config', 'TAG_ID');`
    ]
  ]
}

/* 出力結果:
  <script async src="https://www.googletagmanager.com/gtag/js?id=TAG_ID"></script>
  <script>
    window.dataLayer = window.dataLayer || [];
    function gtag(){dataLayer.push(arguments);}
    gtag('js', new Date());
    gtag('config', 'TAG_ID');
  </script>
*/

lang

型: string
既定値: en-US

サイトの言語属性。ページ HTML の <html lang="en-US"> として出力されます。

export default {
  lang: 'en-US'
}

base

型: string
既定値: /

サイトをデプロイするベース URL。GitHub Pages などサブパス配下にデプロイする場合に設定が必要です。たとえば https://foo.github.io/bar/ にデプロイする場合、base は '/bar/' にします。先頭と末尾は必ずスラッシュにしてください。

/ で始まる他のオプション内の URL には、この base が自動的に付与されます。1 回設定すれば十分です。

export default {
  base: '/base/'
}

ルーティング

cleanUrls

型: boolean
既定値: false

true にすると、URL の末尾の .html を削除します。あわせてクリーン URL の生成も参照してください。

サーバ設定が必要

ホスティング環境によっては追加の設定が必要です。/foo へのアクセス時に リダイレクトなしで /foo.html を返せるサーバ設定が必要です。

rewrites

型: Record<string, string>

ディレクトリと URL のカスタム対応を定義します。詳しくはルーティング: ルートのリライトを参照。

export default {
  rewrites: {
    'source/:page': 'destination/:page'
  }
}

ビルド

srcDir

型: string
既定値: .

Markdown ページを置くディレクトリ（プロジェクトルートからの相対パス）。ルートとソースディレクトリも参照。

export default {
  srcDir: './src'
}

srcExclude

型: string[]
既定値: undefined

ソースとして除外したい Markdown ファイルにマッチする glob パターン。

export default {
  srcExclude: ['**/README.md', '**/TODO.md']
}

outDir

型: string
既定値: ./.vitepress/dist

ビルド出力先（プロジェクトルートからの相対パス）。

export default {
  outDir: '../public'
}

assetsDir

型: string
既定値: assets

生成されるアセットを配置するサブディレクトリ名。パスは outDir の内部で、相対解決されます。

export default {
  assetsDir: 'static'
}

cacheDir

型: string
既定値: ./.vitepress/cache

キャッシュファイル用ディレクトリ（プロジェクトルートからの相対パス）。参考: cacheDir

export default {
  cacheDir: './.vitepress/.vite'
}

ignoreDeadLinks

型: boolean | 'localhostLinks' | (string | RegExp | ((link: string, source: string) => boolean))[]
既定値: false

true にすると、デッドリンクがあってもビルド失敗にしません。

'localhostLinks' にすると、localhost へのリンクはチェック対象外にしつつ、その他のデッドリンクではビルドを失敗させます。

export default {
  ignoreDeadLinks: true
}

正確な URL 文字列、正規表現、カスタムフィルタ関数の配列として指定することもできます。

export default {
  ignoreDeadLinks: [
    // 正確に "/playground" を無視
    '/playground',
    // すべての localhost リンクを無視
    /^https?:\/\/localhost/,
    // パスに "/repl/" を含むリンクを無視
    /\/repl\//,
    // カスタム関数: "ignore" を含むリンクを無視
    (url) => {
      return url.toLowerCase().includes('ignore')
    }
  ]
}

metaChunk experimental

型: boolean
既定値: false

true にすると、各ページのメタデータを初期 HTML にインラインせず、別の JavaScript チャンクに抽出します。これにより各ページの HTML ペイロードが小さくなり、メタデータをキャッシュ可能にすることで、多数のページがあるサイトでサーバ帯域を削減できます。

mpa experimental

型: boolean
既定値: false

true にすると、本番アプリは MPA モードでビルドされます。MPA モードは既定でクライアント JavaScript を 0kb で配信する代わりに、クライアントサイドのナビゲーションを無効にし、相互作用には明示的な opt-in が必要です。

テーマ関連

appearance

型: boolean | 'dark' | 'force-dark' | 'force-auto' | import('@vueuse/core').UseDarkOptions
既定値: true

ダークモードを有効にするか（<html> に .dark クラスを付与）。

true の場合、ユーザーの環境設定に従います。
dark の場合、ユーザーが切り替えない限りダークを既定にします。
false の場合、ユーザーはテーマを切り替えできません。
'force-dark' の場合、常にダークで固定（切替不可）。
'force-auto' の場合、常にユーザーの環境設定に従い（切替不可）。

このオプションは、ローカルストレージの vitepress-theme-appearance から設定を復元するインラインスクリプトを挿入します。これにより、ページ描画前に .dark クラスを適用してフリッカを防ぎます。

appearance.initialValue は 'dark' | undefined のみサポート。Ref や getter は使えません。

lastUpdated

型: boolean
既定値: false

Git を使って各ページの最終更新時刻を取得します。タイムスタンプは各ページのデータに含まれ、useData から参照できます。

デフォルトテーマ使用時にこのオプションを有効にすると、各ページの最終更新時刻が表示されます。テキストは themeConfig.lastUpdatedText でカスタマイズ可能です。

カスタマイズ

markdown

型: MarkdownOption

Markdown パーサの設定。VitePress はパーサに Markdown-it、構文ハイライトに Shiki を使用しています。必要に応じて Markdown 関連の各種オプションを指定できます。

export default {
  markdown: {...}
}

利用可能なオプションは型定義と JSDoc を参照してください。

vite

型: import('vite').UserConfig

内部の Vite 開発サーバ／バンドラへ生の Vite Config を渡します。

export default {
  vite: {
    // Vite の設定
  }
}

vue

型: import('@vitejs/plugin-vue').Options

内部の @vitejs/plugin-vue インスタンスへオプションをそのまま渡します。

export default {
  vue: {
    // @vitejs/plugin-vue のオプション
  }
}

ビルドフック

VitePress のビルドフックを使うと、サイトに機能や振る舞いを追加できます。

サイトマップ
検索インデックス
PWA
Teleport

buildEnd

型: (siteConfig: SiteConfig) => Awaitable<void>

buildEnd はビルド CLI フックです。ビルド（SSG）が完了した後、VitePress CLI プロセスが終了する前に実行されます。

export default {
  async buildEnd(siteConfig) {
    // ...
  }
}

postRender

型: (context: SSGContext) => Awaitable<SSGContext | void>

postRender は SSG のレンダリング完了時に呼ばれるビルドフックです。SSG 中の teleport コンテンツの処理に利用できます。

export default {
  async postRender(context) {
    // ...
  }
}

interface SSGContext {
  content: string
  teleports?: Record<string, string>
  [key: string]: any
}

transformHead

型: (context: TransformContext) => Awaitable<HeadConfig[]>

transformHead は、各ページを生成する前に head を変換するためのビルドフックです。設定ファイルでは静的に追加できない head 要素を追加できます。追加分のみ返せば、既存のものと自動でマージされます。

WARNING

context 内の値は変更しないでください。

export default {
  async transformHead(context) {
    // ...
  }
}

interface TransformContext {
  page: string // 例: index.md（srcDir からの相対）
  assets: string[] // 解決済みの公開 URL（非 js/css アセット）
  siteConfig: SiteConfig
  siteData: SiteData
  pageData: PageData
  title: string
  description: string
  head: HeadConfig[]
  content: string
}

このフックは静的サイト生成時のみ呼ばれ、開発中には呼ばれません。開発中に動的な head 要素を追加したい場合は、代わりに transformPageData を使用できます。

export default {
  transformPageData(pageData) {
    pageData.frontmatter.head ??= []
    pageData.frontmatter.head.push([
      'meta',
      {
        name: 'og:title',
        content:
          pageData.frontmatter.layout === 'home'
            ? `VitePress`
            : `${pageData.title} | VitePress`
      }
    ])
  }
}

例: 正規 URL の `<link>` を追加

export default {
  transformPageData(pageData) {
    const canonicalUrl = `https://example.com/${pageData.relativePath}`
      .replace(/index\.md$/, '')
      .replace(/\.md$/, '.html')

    pageData.frontmatter.head ??= []
    pageData.frontmatter.head.push([
      'link',
      { rel: 'canonical', href: canonicalUrl }
    ])
  }
}

transformHtml

型: (code: string, id: string, context: TransformContext) => Awaitable<string | void>

transformHtml は、各ページの内容をディスクへ保存する前に変換するためのビルドフックです。

WARNING

context 内の値は変更しないでください。また、HTML を変更すると実行時のハイドレーション問題を引き起こす可能性があります。

export default {
  async transformHtml(code, id, context) {
    // ...
  }
}

transformPageData

型: (pageData: PageData, context: TransformPageContext) => Awaitable<Partial<PageData> | { [key: string]: any } | void>

transformPageData は各ページの pageData を変換するためのフックです。pageData を直接変更するか、変更値を返してマージさせることができます。

WARNING

context 内の値は変更しないでください。ネットワークリクエストや重い計算（画像生成など）を行うと開発サーバのパフォーマンスに影響します。process.env.NODE_ENV === 'production' を用いた条件分岐を検討してください。

export default {
  async transformPageData(pageData, { siteConfig }) {
    pageData.contributors = await getPageContributors(pageData.relativePath)
  }

  // あるいはマージ用の値を返す
  async transformPageData(pageData, { siteConfig }) {
    return {
      contributors: await getPageContributors(pageData.relativePath)
    }
  }
}

interface TransformPageContext {
  siteConfig: SiteConfig
}

サイト設定 ​

概要 ​

設定ファイルの解決 ​

設定のインテリセンス ​

型付きのテーマ設定 ​

Vite・Vue・Markdown の設定 ​

サイトメタデータ ​

title ​

titleTemplate ​

description ​

head ​

例: favicon を追加 ​

例: Google Fonts を追加 ​

例: Service Worker を登録 ​

例: Google Analytics を使用 ​

lang ​

base ​

ルーティング ​

cleanUrls ​

rewrites ​

ビルド ​

srcDir ​

srcExclude ​

outDir ​

assetsDir ​

cacheDir ​

ignoreDeadLinks ​

metaChunk experimental ​

mpa experimental ​

テーマ関連 ​

appearance ​

lastUpdated ​

カスタマイズ ​

markdown ​

vite ​

vue ​

ビルドフック ​

buildEnd ​

postRender ​

transformHead ​

例: 正規 URL の <link> を追加 ​

transformHtml ​

transformPageData ​

サイト設定

概要

設定ファイルの解決

設定のインテリセンス

型付きのテーマ設定

Vite・Vue・Markdown の設定

サイトメタデータ

title

titleTemplate

description

head

例: favicon を追加

例: Google Fonts を追加

例: Service Worker を登録

例: Google Analytics を使用

lang

base

ルーティング

cleanUrls

rewrites

ビルド

srcDir

srcExclude

outDir

assetsDir

cacheDir

ignoreDeadLinks

metaChunk experimental

mpa experimental

テーマ関連

appearance

lastUpdated

カスタマイズ

markdown

vite

vue

ビルドフック

buildEnd

postRender

transformHead

例: 正規 URL の `<link>` を追加

transformHtml

transformPageData