vitepress-skilld

[email protected]

Vite と Vue を基盤とする静的サイトジェネレーター（vuejs/vitepress）です。この Skill の信頼できる情報源は準備済みのパッケージソースです。行番号の参照は パッケージルートからの相対パスです（例：dist/node/index.d.ts:2382）。

バージョン情報

• バージョン 1.6.4、MIT（package.json:3）。
• Vue ^3.5.13、Vite ^5.4.14、shiki ^2.1.0、minisearch ^7 をバンドルしています（package.json:59-78）。
• Node.js 18 以降が必要です（https://vitepress.dev/guide/getting-started）。
• VitePress v1 は rolldown-vite と互換性がありません。開発サーバーはエラーを出力し、VitePress v2 を案内します（dist/node/cli.js:438-444）。
• オプションのピア依存関係：markdown-it-mathjax3（markdown.math 用）、postcss（package.json:155-166）。

エントリーポイント

package.json:18-37 のエクスポートマップで定義されています。

インポート	型のエントリー	用途
vitepress	types/index.d.ts	Node、クライアント、共有 API、設定ヘルパー
vitepress/client	client.d.ts	クライアント用コンポーザブル（useData、useRouter、…）
vitepress/theme	theme.d.ts	デフォルトテーマ、useSidebar、useLocalNav
vitepress/theme-without-fonts	theme-without-fonts.d.ts	バンドルされたフォントファイルを含まないデフォルトテーマ

CLI バイナリ：vitepress → bin/vitepress.js。

セットアップとコマンド

npm add -D vitepress
npx vitepress init
npx vitepress dev
npx vitepress build
npx vitepress preview

現在のディレクトリを使用する場合は、dev を省略できます（vitepress のみで実行します）。 serve は preview のエイリアスです。すべてのフラグと開発時のショートカットについては、 cli.md を参照してください。

よくあるタスク

サイト設定（.vitepress/config.ts）

import { defineConfig } from 'vitepress'

export default defineConfig({
  title: 'My App',
  description: 'A VitePress site',
  themeConfig: {
    nav: [{ text: 'Guide', link: '/guide/' }],
    sidebar: [{ text: 'Guide', items: [{ text: 'Intro', link: '/guide/intro' }] }]
  }
})

defineConfig はデフォルトテーマ向けに型付けされています。カスタムテーマには defineConfigWithTheme<CustomThemeConfig> を使用してください （dist/node/index.d.ts:2382-2386）。すべてのオプションについては、 site-config.md を参照してください。

クライアントランタイム API

<script setup>
import { useData, useRouter, withBase } from 'vitepress'
const { page, frontmatter, isDark, hash } = useData()
const router = useRouter()
</script>

エクスポート一覧とシグネチャについては、api.md を参照してください。

ビルド時のデータ読み込み

// posts.data.js
import { createContentLoader } from 'vitepress'
export default createContentLoader('posts/*.md', { excerpt: true })

import { data } from './posts.data.js' としてインポートします。Node でのみ実行され、 結果はクライアントバンドル内に JSON として含まれます。

ブラウザー専用コンポーネント

<script setup>
import { defineClientComponent } from 'vitepress'
const Chart = defineClientComponent(() => import('./Chart.vue'))
</script>

インポート時にライブラリが window／document にアクセスする場合に発生する SSG ビルドの失敗を防ぎます（https://vitepress.dev/guide/ssr-compat）。

ベストプラクティス

• アーカイブページやインデックスページでは、独自のローダーを作成する代わりに createContentLoader を使用してください。ファイルの更新時刻を基準にキャッシュし、 クライアントの JSON を小さく保てます （dist/node/index.d.ts:2466-2473、https://vitepress.dev/guide/data-loading）。
• ブラウザー専用コンポーネントは defineClientComponent でラップしてください （https://vitepress.dev/guide/ssr-compat）。
• Markdown 内の画像とアセットの URL は相対パスにしてください。Vite がハッシュ化してインライン化します。 テーマコンポーネント内の動的なパスには withBase() を使用してください （https://vitepress.dev/guide/asset-handling）。
• ホスト側で /foo を /foo.html にマッピングできる場合に限り、cleanUrls: true を有効にしてください （https://vitepress.dev/guide/routing#clean-urls）。
• rewrites を使用する場合、相対リンクの参照先はソースファイルの構造ではなく、 書き換え後の URL 構造にしてください （https://vitepress.dev/guide/routing#route-rewrites）。
• 動的ルートの paths.js ローダーでは、クライアントの JS を小さく保つため、 大きなペイロードは params ではなく content 経由で渡してください （https://vitepress.dev/guide/routing#dynamic-routes）。
• MPA モード（mpa: true）では、インタラクティブ機能に <script client> を使用してください。 通常の <script setup> はサーバーサイドのテンプレート処理のみです （https://vitepress.dev/guide/mpa-mode）。
• _render フックを使って、ページをローカル検索の対象から除外してください （types/default-theme.d.ts:451-455）。

詳細なリファレンス

• api.md：vitepress、vitepress/client、vitepress/theme のすべてのエクスポート、データローダーの型、テーマインターフェース。
• site-config.md：UserConfig のフィールド、ビルドフック、SiteConfig、mergeConfig。
• default-theme.md：DefaultTheme.Config、ナビゲーション、サイドバー、検索（ローカルおよび algolia）、テーマの拡張。
• markdown.md：markdown のオプション、shiki のセットアップ、コンテナー、数式、createMarkdownRenderer。
• cli.md：コマンド、フラグ、開発時のショートカット、スキャフォールディング。
• migration.md：v0 → v1 の破壊的変更と、1.6.4 でも確認できる非推奨項目。

バージョン固有の変更

古い設定を変更する場合は、以下を優先してください。詳細と出典は migration.md を参照してください。

• 破壊的変更（v1.0.0-rc.9）：pathname:// プロトコルを削除しました。target="_self" または target="_blank" を使用してください （https://github.com/vuejs/vitepress/blob/main/CHANGELOG.md）。
• 破壊的変更（v1.0.0）：サイドバーの children を items に変更しました。最上位の項目では link を指定できなくなりました （https://vitepress.dev/guide/migration-from-vitepress-0）。
• 破壊的変更（v1.0.0-alpha.44）：collapsible を collapsed: boolean に置き換えました（CHANGELOG）。
• 破壊的変更（v1.0.0-alpha.57）：markdown.headers はデフォルトで無効になりました。有効にしない限り、PageData.headers は空です（CHANGELOG）。
• markdown.headers を有効にした場合、抽出レベルのデフォルトは [2, 3] です （dist/node/index.d.ts:1769-1786）。
• 新機能（v1.1.0）：useData().hash はリアクティブな URL ハッシュです （dist/client/index.d.ts:79-83）。
• 新機能（v1.4.0）：onAfterPageLoad ルーターフック （dist/client/index.d.ts:36-38）。
• 新機能（v1.3.0）：appearance: 'force-auto' （types/shared.d.ts:119-124）。
• 1.6.4 で非推奨：Theme.setup、Theme.NotFound （dist/client/index.d.ts:96-103）、outlineTitle、lastUpdatedText、 algolia テーマオプション（types/default-theme.d.ts:36-77,139-141）。