はじめに
オンラインで試す
ブラウザで直接VitePressを試すことができます。StackBlitz。
インストール
前提条件
VitePressは単独で使用することも、既存のプロジェクトにインストールすることもできます。どちらの場合も、以下を使用してインストールできます。
$ npm add -D vitepress$ pnpm add -D vitepress$ yarn add -D vitepress$ bun add -D vitepressピア依存関係の警告が表示される場合
PNPMを使用している場合、`@docsearch/js` のピア依存関係がないという警告が表示されます。これはVitePressの動作を妨げません。この警告を抑制する場合は、次の内容を`package.json`に追加してください。
"pnpm": {
"peerDependencyRules": {
"ignoreMissing": [
"@algolia/client-search",
"search-insights"
]
}
}注意
VitePressはESM専用のライブラリです。`require()`を使用してインポートしないでください。また、最も近い`package.json`に`"type": "module"`が含まれていることを確認するか、` .vitepress/config.js`などの関連ファイルの拡張子を` .mjs`/` .mts`に変更してください。Viteのトラブルシューティングガイドで詳細を確認してください。また、非同期CJSコンテキスト内では、`await import('vitepress')`を使用できます。
セットアップウィザード
VitePressには、基本的なプロジェクトをスキャフォールディングするのに役立つコマンドラインセットアップウィザードが付属しています。インストール後、次を実行してウィザードを開始します。
$ npx vitepress init$ pnpm vitepress init$ yarn vitepress init$ bun vitepress initいくつかの簡単な質問が表示されます。
┌ Welcome to VitePress!
│
◇ Where should VitePress initialize the config?
│ ./docs
│
◇ Site title:
│ My Awesome Project
│
◇ Site description:
│ A VitePress Site
│
◆ Theme:
│ ● Default Theme (Out of the box, good-looking docs)
│ ○ Default Theme + Customization
│ ○ Custom Theme
└Vueをピア依存関係として
VueコンポーネントまたはAPIを使用するカスタマイズを行う場合は、`vue`を依存関係として明示的にインストールする必要があります。
ファイル構造
スタンドアロンのVitePressサイトを構築する場合は、現在のディレクトリ（`./`）にサイトをスキャフォールディングできます。ただし、他のソースコードとともに既存のプロジェクトにVitePressをインストールする場合は、プロジェクトの他の部分とは別に配置するために、ネストされたディレクトリ（例：`./docs`）にサイトをスキャフォールディングすることをお勧めします。
VitePressプロジェクトを`./docs`にスキャフォールディングすることを選択した場合、生成されたファイル構造は次のようになります。
.
├─ docs
│ ├─ .vitepress
│ │ └─ config.js
│ ├─ api-examples.md
│ ├─ markdown-examples.md
│ └─ index.md
└─ package.json`docs`ディレクトリは、VitePressサイトの**プロジェクトルート**と見なされます。`.vitepress`ディレクトリは、VitePressの設定ファイル、開発サーバーのキャッシュ、ビルド出力、およびオプションのテーマのカスタマイズコードを格納するための予約済み場所です。
ヒント
デフォルトでは、VitePressは開発サーバーのキャッシュを`.vitepress/cache`に、本番ビルド出力を`.vitepress/dist`に格納します。Gitを使用している場合は、` .gitignore`ファイルに追加する必要があります。これらの場所は設定することもできます。
設定ファイル
設定ファイル（`.vitepress/config.js`）を使用すると、サイトのタイトルと説明など、VitePressサイトのさまざまな側面をカスタマイズできます。
// .vitepress/config.js
export default {
// site-level options
title: 'VitePress',
description: 'Just playing around.',
themeConfig: {
// theme-level options
}
}`themeConfig`オプションを使用して、テーマの動作を設定することもできます。すべての設定オプションの詳細については、設定リファレンスを参照してください。
ソースファイル
`.vitepress`ディレクトリ外のMarkdownファイルは、**ソースファイル**と見なされます。
VitePressは**ファイルベースのルーティング**を使用します。各`.md`ファイルは、同じパスを持つ対応する`.html`ファイルにコンパイルされます。たとえば、`index.md`は`index.html`にコンパイルされ、結果のVitePressサイトのルートパス`/`でアクセスできます。
VitePressは、クリーンなURLの生成、パスの書き換え、動的なページ生成も可能です。これについては、ルーティングガイドで説明します。
実行開始
セットアッププロセス中に許可した場合、このツールは次のnpmスクリプトを`package.json`に挿入しているはずです。
{
...
"scripts": {
"docs:dev": "vitepress dev docs",
"docs:build": "vitepress build docs",
"docs:preview": "vitepress preview docs"
},
...
}`docs:dev`スクリプトは、インスタントホットアップデートによるローカル開発サーバーを開始します。次のコマンドで実行します。
$ npm run docs:dev$ pnpm run docs:dev$ yarn docs:dev$ bun run docs:devnpmスクリプトの代わりに、VitePressを直接呼び出すこともできます。
$ 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コンポーネントの使用など、ページでできることをさらに理解するには、ガイドの「ライティング」セクションを参照してください。まずMarkdown拡張機能について学ぶのが良いでしょう。
デフォルトのドキュメントテーマによって提供される機能について調べるには、デフォルトテーマ設定リファレンスを確認してください。
サイトの外観をさらにカスタマイズする場合は、デフォルトテーマの拡張またはカスタムテーマの構築の方法を調べてください。
ドキュメントサイトが形になったら、デプロイガイドを読んでください。