VitePress

英語

簡体字中国語
ポルトガル語
ロシア語
韓国語

英語

簡体字中国語
ポルトガル語
ロシア語
韓国語

外観

サイト設定 ​

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

概要 ​

設定の解決 ​

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

設定ファイルではESモジュール構文を使用することをお勧めします。設定ファイルはオブジェクトをデフォルトエクスポートする必要があります。

ts
export default {
  // app level config options
  lang: 'en-US',
  title: 'VitePress',
  description: 'Vite & Vue powered static site generator.',
  ...
}
動的（非同期）設定

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

ts
import { defineConfig } from 'vitepress'

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

  return defineConfig({
    // app level config options
    lang: 'en-US',
    title: 'VitePress',
    description: 'Vite & Vue powered static site generator.',

    // theme level config options
    themeConfig: {
      sidebar: [
        ...posts.map((post) => ({
          text: post.name,
          link: `/posts/${post.name}`
        }))
      ]
    }
  })
}

トップレベルの`await`を使用することもできます。例:

ts
import { defineConfig } from 'vitepress'

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

export default defineConfig({
  // app level config options
  lang: 'en-US',
  title: 'VitePress',
  description: 'Vite & Vue powered static site generator.',

  // theme level config options
  themeConfig: {
    sidebar: [
      ...posts.map((post) => ({
        text: post.name,
        link: `/posts/${post.name}`
      }))
    ]
  }
})

設定インテリセンス ​

`defineConfig`ヘルパーを使用すると、設定オプションのTypeScript対応インテリセンスが提供されます。IDEがサポートしている場合、JavaScriptとTypeScriptの両方で動作します。

js
import { defineConfig } from 'vitepress'

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

型付きテーマ設定 ​

デフォルトでは、`defineConfig`ヘルパーはデフォルトテーマからテーマ設定の型を期待します。

ts
import { defineConfig } from 'vitepress'

export default defineConfig({
  themeConfig: {
    // Type is `DefaultTheme.Config`
  }
})

カスタムテーマを使用していて、テーマ設定の型チェックが必要な場合は、代わりに`defineConfigWithTheme`を使用し、ジェネリック引数を使用してカスタムテーマの設定型を渡す必要があります。

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

export default defineConfigWithTheme<ThemeConfig>({
  themeConfig: {
    // Type is `ThemeConfig`
  }
})

Vite、Vue、Markdown設定 ​

  • Vite

    VitePressの設定でviteオプションを使用して、基となるViteインスタンスを設定できます。個別のVite設定ファイルを作成する必要はありません。

  • Vue

    VitePressには既にViteの公式Vueプラグイン（@vitejs/plugin-vue）が含まれています。VitePressの設定でvueオプションを使用して、そのオプションを設定できます。

  • Markdown

    VitePressの設定でmarkdownオプションを使用して、基となるMarkdown-Itインスタンスを設定できます。

サイトメタデータ ​

title ​

  • 型: `string`
  • デフォルト: `VitePress`
  • フロントマターを介してページごとに上書きできます。

サイトのタイトル。デフォルトテーマを使用している場合、これはナビゲーションバーに表示されます。

また、titleTemplateが定義されていない限り、すべての個々のページタイトルのデフォルトのサフィックスとしても使用されます。個々のページの最終的なタイトルは、最初の<h1>ヘッダーのテキストコンテンツと、グローバルtitleをサフィックスとして組み合わせたものになります。次の設定とページコンテンツの場合:

ts
export default {
  title: 'My Awesome Site'
}
md
# Hello

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

titleTemplate ​

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

ts
export default {
  title: 'My Awesome Site',
  titleTemplate: 'Custom Suffix'
}
md
# Hello

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

タイトルのレンダリング方法を完全にカスタマイズするには、titleTemplateで`:title`記号を使用できます。

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

ここでは、`:title`はページの最初の<h1>ヘッダーから推測されたテキストに置き換えられます。前の例のページのタイトルは`Hello - Custom Suffix`になります。

タイトルのサフィックスを無効にするには、このオプションを`false`に設定できます。

description ​

  • 型: `string`
  • デフォルト: `A VitePress site`
  • フロントマターを介してページごとに上書きできます。

サイトの説明。これはページのHTMLで<meta>タグとしてレンダリングされます。

ts
export default {
  description: 'A VitePress site'
}
  • 型: `HeadConfig[]`
  • デフォルト: `[]`
  • フロントマターを介してページごとに追加できます。

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

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

例：ファビコンの追加 ​

ts
export default {
  head: [['link', { rel: 'icon', href: '/favicon.ico' }]]
} // put favicon.ico in public directory, if base is set, use /base/favicon.ico

/* Would render:
  <link rel="icon" href="/favicon.ico">
*/

例：Googleフォントの追加 ​

ts
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' }
    ]
  ]
}

/* Would render:
  <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">
*/

例：サービスワーカーの登録 ​

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

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

例：Googleアナリティクスの使用 ​

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

/* Would render:
  <script async src="https://#/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`

サイトのlang属性。これはページのHTMLで<html lang="en-US">タグとしてレンダリングされます。

ts
export default {
  lang: 'en-US'
}

base ​

  • 型: `string`
  • デフォルト: `/`

サイトが配置されるベースURL。サイトをサブパス（例：GitHub Pages）に配置する予定がある場合は、これを設定する必要があります。サイトを`https://foo.github.io/bar/`に配置する予定がある場合は、baseを`'/bar/'`に設定する必要があります。常にスラッシュで始まり、スラッシュで終わる必要があります。

baseは、他のオプションで`/`で始まるすべてのURLの前に自動的に追加されるため、一度だけ指定する必要があります。

ts
export default {
  base: '/base/'
}

ルーティング ​

cleanUrls ​

  • 型: `boolean`
  • デフォルト: `false`

`true`に設定すると、VitePressはURLから末尾の`.html`を削除します。クリーンURLの生成も参照してください。

サーバーサポートが必要

これを有効にするには、ホスティングプラットフォームで追加の設定が必要になる場合があります。機能させるには、サーバーは` /foo`にアクセスするときに` /foo.html`を提供できる必要があります（**リダイレクトなし**）。

rewrites ​

  • 型: `Record<string, string>`

カスタムディレクトリ<->URLマッピングを定義します。ルーティング：ルートの書き換えの詳細を参照してください。

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

ビルド ​

srcDir ​

  • 型: `string`
  • デフォルト: `.`

Markdownページが格納されているディレクトリ（プロジェクトルートを基準とする相対パス）。ルートとソースディレクトリも参照してください。

ts
export default {
  srcDir: './src'
}

srcExclude ​

  • 型: `string`
  • デフォルト: `undefined`

ソースコンテンツとして除外する必要があるMarkdownファイルに一致するglobパターン。

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

outDir ​

  • 型: `string`
  • デフォルト: `./.vitepress/dist`

サイトのビルド出力場所（プロジェクトルートを基準とする相対パス）。

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

assetsDir ​

  • 型: `string`
  • デフォルト: `assets`

生成されたアセットをネストするディレクトリを指定します。このパスはoutDir内にあり、それに対して解決されます。

ts
export default {
  assetsDir: 'static'
}

cacheDir ​

  • 型: `string`
  • デフォルト: `./.vitepress/cache`

キャッシュファイルのディレクトリ（プロジェクトルートを基準とする相対パス）。cacheDirも参照してください。

ts
export default {
  cacheDir: './.vitepress/.vite'
}
  • 型: `boolean | 'localhostLinks' | (string | RegExp | ((link: string) => boolean))[]`
  • デフォルト: `false`

`true`に設定すると、VitePressは壊れたリンクによってビルドが失敗しなくなります。

`'localhostLinks'`に設定すると、壊れたリンクでビルドは失敗しますが、`localhost`リンクはチェックしません。

ts
export default {
  ignoreDeadLinks: true
}

正確なURL文字列、正規表現パターン、またはカスタムフィルタ関数の配列にすることもできます。

ts
export default {
  ignoreDeadLinks: [
    // ignore exact url "/playground"
    '/playground',
    // ignore all localhost links
    /^https?:\/\/localhost/,
    // ignore all links include "/repl/""
    /\/repl\//,
    // custom function, ignore all links include "ignore"
    (url) => {
      return url.toLowerCase().includes('ignore')
    }
  ]
}

metaChunk 実験的 ​

  • 型: `boolean`
  • デフォルト: `false`

`true`に設定すると、ページのメタデータを個別のJavaScriptチャンクに抽出します。これにより、各ページのHTMLペイロードが小さくなり、ページのメタデータがキャッシュ可能になり、サイトに多くのページがある場合のサーバー帯域幅が削減されます。

mpa 実験的 ​

  • 型: `boolean`
  • デフォルト: `false`

trueに設定すると、プロダクションアプリはMPAモードでビルドされます。MPAモードではデフォルトで0kbのJavaScriptしか出荷されませんが、クライアントサイドでのナビゲーションが無効になり、インタラクティブ機能を使用するには明示的にオプトインする必要があります。

テーマ設定 ​

外観 ​

  • 型: boolean | 'dark' | 'force-dark' | import('@vueuse/core').UseDarkOptions
  • デフォルト: true

ダークモードを有効にするかどうか（<html>要素に.darkクラスを追加します）。

  • このオプションをtrueに設定すると、デフォルトのテーマはユーザーの好みのカラースキームによって決定されます。
  • このオプションをdarkに設定すると、ユーザーが手動で切り替えない限り、デフォルトのテーマはダークになります。
  • このオプションをfalseに設定すると、ユーザーはテーマを切り替えることができなくなります。

このオプションは、vitepress-theme-appearanceキーを使用してローカルストレージからユーザー設定を復元するインラインスクリプトを挿入します。これにより、ページがレンダリングされる前に.darkクラスが適用され、ちらつきを防ぎます。

appearance.initialValueは'dark' | undefinedのみ可能です。Refやgetterはサポートされていません。

最終更新日 ​

  • 型: `boolean`
  • デフォルト: `false`

Gitを使用して各ページの最終更新タイムスタンプを取得するかどうか。タイムスタンプは各ページのページデータに含まれ、useDataからアクセスできます。

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

カスタマイズ ​

マークダウン ​

  • 型: MarkdownOption

マークダウンパーサーオプションを設定します。VitePressはパーサーとしてMarkdown-itを、言語構文のハイライトにはShikiを使用します。このオプション内では、ニーズに合わせてさまざまなマークダウン関連オプションを渡すことができます。

js
export default {
  markdown: {...}
}

利用可能なすべてのオプションについては、型宣言とjsdocsを確認してください。

vite ​

  • 型: import('vite').UserConfig

内部Vite開発サーバー/バンドラーに生のVite設定を渡します。

js
export default {
  vite: {
    // Vite config options
  }
}

vue ​

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

内部プラグインインスタンスに生の@vitejs/plugin-vueオプションを渡します。

js
export default {
  vue: {
    // @vitejs/plugin-vue options
  }
}

ビルドフック ​

VitePressビルドフックを使用すると、ウェブサイトに新しい機能と動作を追加できます。

  • サイトマップ
  • 検索インデックス
  • PWA
  • テレポート

buildEnd ​

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

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

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

postRender ​

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

postRenderはビルドフックで、SSGレンダリングが完了したときに呼び出されます。これにより、SSG中にテレポートコンテンツを処理できます。

ts
export default {
  async postRender(context) {
    // ...
  }
}
ts
interface SSGContext {
  content: string
  teleports?: Record<string, string>
  [key: string]: any
}

transformHead ​

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

transformHeadは、各ページを生成する前にheadを変換するためのビルドフックです。VitePress設定に静的に追加できないheadエントリを追加できます。追加のエントリを返すだけで、既存のエントリと自動的にマージされます。

警告

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

ts
export default {
  async transformHead(context) {
    // ...
  }
}
ts
interface TransformContext {
  page: string // e.g. index.md (relative to srcDir)
  assets: string[] // all non-js/css assets as fully resolved public URL
  siteConfig: SiteConfig
  siteData: SiteData
  pageData: PageData
  title: string
  description: string
  head: HeadConfig[]
  content: string
}

このフックはサイトを静的に生成する場合にのみ呼び出されます。開発中は呼び出されません。開発中に動的なheadエントリを追加する必要がある場合は、代わりにtransformPageDataフックを使用できます。

ts
export default {
  transformPageData(pageData) {
    pageData.frontmatter.head ??= []
    pageData.frontmatter.head.push([
      'meta',
      {
        name: 'og:title',
        content:
          pageData.frontmatter.layout === 'home'
            ? `VitePress`
            : `${pageData.title} | VitePress`
      }
    ])
  }
}
ts
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は、ディスクに保存する前に各ページのコンテンツを変換するためのビルドフックです。

警告

context内のものは変更しないでください。また、htmlコンテンツを変更すると、実行時にhydrationの問題が発生する可能性があります。

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

transformPageData ​

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

transformPageDataは、各ページのpageDataを変換するためのフックです。pageDataを直接変更するか、変更された値を返し、ページデータにマージできます。

警告

context内のものは変更しないでください。また、ネットワークリクエストや重い計算（画像の生成など）をフックで行うと、特に開発サーバーのパフォーマンスに影響を与える可能性があることに注意してください。条件付きロジックにはprocess.env.NODE_ENV === 'production'を確認できます。

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

  // or return data to be merged
  async transformPageData(pageData, { siteConfig }) {
    return {
      contributors: await getPageContributors(pageData.relativePath)
    }
  }
}
ts
interface TransformPageContext {
  siteConfig: SiteConfig
}

MITライセンスの下でリリースされています。

Copyright © 2019-present Evan You