7.2 KiB
はじめに
オンラインで試す
VitePress をブラウザ上で直接試すことができます。
インストール
前提条件
VitePress は単独でも利用できますし、既存プロジェクトに組み込むことも可能です。いずれの場合も以下でインストールできます。
::: code-group
$ npm add -D vitepress@next
$ pnpm add -D vitepress@next
$ yarn add -D vitepress@next vue
$ bun add -D vitepress@next
:::
::: tip 注意
VitePress は ESM 専用パッケージです。require() を使ってインポートせず、最も近い package.json に "type": "module" を含めるか、.vitepress/config.js を .mjs / .mts に変更してください。詳しくは Vite のトラブルシューティングガイド を参照してください。また、非同期 CJS コンテキスト内では await import('vitepress') を使用できます。
:::
セットアップウィザード
VitePress にはコマンドラインのセットアップウィザードが付属しており、基本的なプロジェクトを簡単に作成できます。インストール後、以下のコマンドでウィザードを起動します。
::: code-group
$ npx vitepress init
$ pnpm vitepress init
$ yarn vitepress init
$ bun vitepress init
:::
いくつかの簡単な質問が表示されます。
<<< @/snippets/init.ansi
::: tip Vue をピア依存関係に
Vue コンポーネントや API を使ったカスタマイズを行う場合は、明示的に vue を依存関係としてインストールしてください。
:::
ファイル構成
スタンドアロンの VitePress サイトを構築する場合は、現在のディレクトリ (./) にサイトを作成できます。しかし、既存プロジェクトに VitePress を追加する場合は、他のソースコードと分離するために ./docs などのサブディレクトリに作成することをおすすめします。
例えば ./docs に VitePress プロジェクトを作成した場合、生成されるファイル構成は以下のようになります。
.
├─ docs
│ ├─ .vitepress
│ │ └─ config.js
│ ├─ api-examples.md
│ ├─ markdown-examples.md
│ └─ index.md
└─ package.json
docs ディレクトリが VitePress サイトの プロジェクトルート とみなされます。.vitepress ディレクトリは VitePress の設定ファイル、開発サーバーのキャッシュ、ビルド出力、テーマのカスタマイズコードなどに予約されています。
::: tip
デフォルトでは開発サーバーのキャッシュは .vitepress/cache に、本番ビルド出力は .vitepress/dist に保存されます。Git を使用している場合は .gitignore に追加してください。これらの場所は 設定 で変更可能です。
:::
設定ファイル
設定ファイル (.vitepress/config.js) では、VitePress サイトのさまざまな動作をカスタマイズできます。最も基本的なオプションはサイトのタイトルと説明です。
export default {
// サイトレベルのオプション
title: 'VitePress',
description: 'Just playing around.',
themeConfig: {
// テーマレベルのオプション
}
}
テーマの動作は themeConfig オプションで設定できます。利用可能なすべての設定オプションは Config Reference を参照してください。
ソースファイル
.vitepress ディレクトリ外の Markdown ファイルは ソースファイル とみなされます。
VitePress は ファイルベースのルーティング を採用しています。各 .md ファイルは同じパスを持つ .html ファイルにコンパイルされます。例えば index.md は index.html にコンパイルされ、サイトのルート / で表示されます。
VitePress にはクリーン URL の生成、パスの書き換え、動的なページ生成といった機能もあります。これらは ルーティングガイド で解説します。
実行してみる
セットアッププロセスで許可した場合、以下の npm スクリプトが package.json に追加されています。
{
...
"scripts": {
"docs:dev": "vitepress dev docs",
"docs:build": "vitepress build docs",
"docs:preview": "vitepress preview docs"
},
...
}
docs:dev スクリプトを実行すると、即時ホットリロード対応のローカル開発サーバーが起動します。次のコマンドで実行します。
::: code-group
$ npm run docs:dev
$ pnpm run docs:dev
$ yarn docs:dev
$ bun run docs:dev
:::
npm スクリプトではなく、直接 VitePress を実行することもできます。
::: code-group
$ npx vitepress dev docs
$ pnpm vitepress dev docs
$ yarn vitepress dev docs
$ bun vitepress dev docs
:::
その他のコマンドラインの使い方は CLI リファレンス に記載されています。
開発サーバーは http://localhost:5173 で動作します。ブラウザでこの URL にアクセスすると、新しいサイトが確認できます。
次のステップ
-
Markdown ファイルがどのように HTML にマッピングされるかを理解するには、ルーティングガイド を読みましょう。
-
ページ内でできること（Markdown コンテンツの記述や Vue コンポーネントの利用など）を知るには、ガイドの「Writing」セクションを参照してください。まずは Markdown 拡張 を学ぶのがおすすめです。
-
デフォルトドキュメントテーマの機能を知りたい場合は、Default Theme Config Reference を確認してください。
-
サイトの見た目をさらにカスタマイズしたい場合は、デフォルトテーマの拡張 や カスタムテーマの構築 を検討してください。
-
ドキュメントサイトが形になったら、必ず デプロイガイド を読んでください。