VitePressでドキュメントサイトを作ってみたら快適すぎた話

はじめに

技術ドキュメントやブログを作りたいとき、何を使うか迷いますよね。

個人的には「VitePress」が現時点での最適解だと思っています。GitHubで16,600スター以上、月間150万ダウンロードという数字がその人気を物語っていますね。

正直なところ、最初は「VuePressの後継？また乗り換えるのか...」と思っていたんですよ。でも実際に使ってみたら、Viteベースになったことで開発体験が段違い。ドキュメントサイトを作るなら、これ一択ですね。

VitePressとは

VitePressはVue.jsとViteを活用した静的サイトジェネレーター（SSG）です。VuePressの精神的後継として、Vue.js作者のEvan You氏らが開発しています。

現在の最新バージョンはv2.0.0-alpha.15（2025年11月時点）で、MITライセンスのオープンソースとして公開されています。400人以上のコントリビューターがいて、46,700以上のプロジェクトがVitePressに依存しているという規模感です。

特徴・メリット

1. Viteベースで爆速

これ、意外と重要なんですよね。

VuePressを使っていた人ならわかると思うんですけど、プロジェクトが大きくなると開発サーバーの起動やHMRが遅くなっていく。VitePressはViteの恩恵をそのまま受けられるので、サーバー起動がほぼ瞬時。ファイル保存したらすぐに反映される。

30代になって思うのは、こういう「待ち時間」の積み重ねが馬鹿にならないということ。

2. Markdownだけで美しいサイトが作れる

ドキュメントサイトって、結局Markdownで書けるのが一番効率的なんですよ。

VitePressはMarkdownを書くだけで、自動的にきれいなドキュメントサイトになる。シンタックスハイライト、目次生成、レスポンシブデザイン...全部デフォルトで付いてくる。

3. Vue統合がシームレス

ここがVitePressの強みですね。

Markdown内で直接Vueコンポーネントを使える。ちょっとしたインタラクティブな要素を追加したいとき、別途設定なしでVueのパワーを使えるのは大きい。

<!-- Markdown内でVueコンポーネントを使える -->
<CustomButton text="クリック" />

4. パフォーマンスが優秀

初期読み込みは静的HTMLで高速。その後のナビゲーションはSPA的に動作するので、ページ遷移も滑らか。

静的サイトジェネレーターなのにSPAっぽい体験ができる。これ、意外と珍しいんですよね。

5. デフォルトテーマが洗練されている

正直、デフォルトテーマのまま使っても十分おしゃれ。サイドバー、ナビゲーション、検索機能...ドキュメントサイトに必要なものは全部揃っている。

カスタマイズしたければVueコンポーネントで上書きできるので、自由度も高い。

インストール方法

前提条件

Node.js 18以上が必要です。

新規プロジェクトの場合

# npm
npm add -D vitepress@next

# pnpm（推奨）
pnpm add -D vitepress@next

# yarn
yarn add -D vitepress@next vue

# bun
bun add -D vitepress@next

セットアップウィザード

インストール後、ウィザードを実行するのが一番楽です。

npx vitepress init

対話形式で以下を聞かれます：

VitePressを配置するディレクトリ
サイトのタイトル
サイトの説明
テーマ設定
TypeScriptを使うか
package.jsonにスクリプトを追加するか

開発サーバーの起動

npm run docs:dev

http://localhost:5173で開発サーバーが立ち上がります。起動時間は体感で1秒未満。

基本的な使い方

ディレクトリ構成

ウィザードで作成すると、こんな構成になります。

.
├── .vitepress/
│   └── config.mts      # 設定ファイル
├── api-examples.md     # サンプルページ
├── markdown-examples.md
├── index.md            # トップページ
└── package.json

設定ファイル

.vitepress/config.mtsで基本設定を行います。

import { defineConfig } from 'vitepress'

export default defineConfig({
  title: 'My Docs',
  description: 'ドキュメントサイトの説明',

  themeConfig: {
    // ナビゲーション
    nav: [
      { text: 'Home', link: '/' },
      { text: 'Guide', link: '/guide/' }
    ],

    // サイドバー
    sidebar: [
      {
        text: 'はじめに',
        items: [
          { text: 'インストール', link: '/guide/install' },
          { text: 'クイックスタート', link: '/guide/quickstart' }
        ]
      }
    ],

    // ソーシャルリンク
    socialLinks: [
      { icon: 'github', link: 'https://github.com/your-repo' }
    ]
  }
})

フロントマター

各Markdownファイルの先頭でメタデータを設定できます。

---
title: ページタイトル
description: ページの説明
outline: [2, 3]  # 目次に表示する見出しレベル
---

コードブロック

シンタックスハイライトはデフォルトで有効。行のハイライトも簡単。

function greet(name: string) {
  console.log(`Hello, ${name}!`)  // この行がハイライト

  return {                         // この行と
    message: 'Welcome'             // この行がハイライト
  }
}

本番ビルド

npm run docs:build

.vitepress/distに静的ファイルが出力されます。これをそのままホスティングすればOK。

実践的なユースケース

OSSプロジェクトのドキュメント

Vue.js、Vite、Vitest...多くの有名OSSがVitePressを使っています。

理由は明確で、Markdownで書けて、必要に応じてVueコンポーネントも使えて、パフォーマンスも良い。メンテナンスコストが低いんですよね。

技術ブログ

ブログ機能もあります。ブログ用のテーマ設定をすれば、記事一覧やタグ機能も使える。

// .vitepress/config.mts
export default defineConfig({
  // ブログっぽいURL構造
  rewrites: {
    'posts/:slug.md': ':slug.md'
  }
})

社内ドキュメント

これ、意外と需要あるんですよね。

社内のナレッジベースやAPI仕様書をVitePressで管理している会社も増えてきました。Gitで管理できて、レビューもしやすい。

多言語対応

国際化（i18n）もビルトインでサポート。

export default defineConfig({
  locales: {
    root: {
      label: '日本語',
      lang: 'ja'
    },
    en: {
      label: 'English',
      lang: 'en'
    }
  }
})

VuePressからの移行

VuePressを使っている人は、移行を検討する価値があります。

移行のポイント：

設定ファイルの形式変更
- .vuepress/config.js → .vitepress/config.mts
- TypeScriptがデフォルトに
テーマの差異
- デフォルトテーマのコンポーネント名が変わっている箇所あり
プラグインの互換性
- VuePressのプラグインはそのまま使えない
- VitePress用に書き直すか、代替を探す必要あり