---
title: "VitePressとは：Vue製ドキュメントサイトの作り方と1.6系・2.0版の選び方【2026年11月版】"
url: "https://www.issoh.co.jp/tech/details/19167/"
published: 2026-11-01
updated: 2026-11-01
categories: ["開発"]
publisher: "株式会社一創"
---

# VitePressとは：Vue製ドキュメントサイトの作り方と1.6系・2.0版の選び方【2026年11月版】

VitePressは、Markdownで書いた原稿から静的なドキュメントサイトを生成する、Vue 3とVite製のオープンソースツールです。Vite、Vitest、Piniaなどの公式ドキュメントもVitePressで作られています。2026年11月1日にnpm registryで確認した`vitepress`のlatestは1.6.4（2025年8月5日公開）で、公式サイトの手順は開発中の2.0.0-alpha.21を前提に書かれていました。この記事では、VitePressの仕組みと新規作成からビルドまでの手順、テーマのカスタマイズ、日本語の検索と多言語化、GitHub Pagesへの公開、どちらの版で始めるか、Docusaurusとの選び分けまでを公式ドキュメントとCHANGELOGをもとに整理します。

## まとめ：VitePressを選んでよい条件と1.6系で始めるか2.0を待つかの結論

結論から書きます。1つの製品について1つの版の説明書を作り、保守する人がVueかHTMLとCSSを書ける。この条件ならVitePressは有力な候補です。初期設定のままで日本語の全文検索がブラウザ内で動き、外部の検索サービスに申請する作業も要りません。

見送るべきなのは、製品の版ごとに説明書を出し分けたい場合です。VitePressの公式ガイドにはバージョニングの章が無く、版の切り替えは自前で組むことになります。その要件があるならDocusaurusが先に候補になります。

版の選び方も先に示します。本番で長く使うサイトは、npm latestの1.6系で作ります。2.0はalphaのまま破壊的変更が続いており、2026年7月のalpha.18ではVite 8への移行とNode.js 20の対応終了が入りました。新規に作るなら、CIのNode.jsだけは22以上へ上げておくと、2.0の正式版へ移る作業が軽くなります。

## VitePressの定義｜Vue 3とViteで動くVuePress後継の静的サイト生成

まず、VitePressが何を受け持つツールなのかを押さえます。

### Markdownを静的HTMLとVueのSPAで出力する仕組みと初回表示

公式の[What is VitePress?](https://vitepress.dev/guide/what-is-vitepress)によると、VitePressはMarkdownにテーマを当てて静的HTMLを書き出し、初回アクセスではそのHTMLを返します。読み込み後はVueのSPAとして動き、2ページ目以降はページ全体を読み直さずに本文だけを差し替える仕組みです。画面内に見えているリンク先は、先読みもしています。

本文のうち静的な部分はJavaScriptの配信対象から外され、ハイドレーションでも処理されません。Markdownの中にVueコンポーネントを埋め込んでも、動く部分だけが重くなる作りです。静的サイト生成という方式そのものの利点と制約は、[静的サイトジェネレーターの仕組みと企業サイトでの採用判断](https://www.issoh.co.jp/column/details/17699/)で整理しています。

### VuePress 1との関係とVite・Vitest・Piniaが採用している実績

同じページは、VitePressをVuePress 1の精神的な後継と位置付けています。VuePress 1はVue 2とwebpackが土台でしたが、VitePressはVue 3とViteに置き換えました。VuePress 1はすでに非推奨で、Vueチームは長期的に推奨するSSGとしてVitePressに注力すると書いています。

採用例として挙がっているのは、Vite、Rollup、Pinia、VueUse、Vitestのドキュメントです。開発サーバーの起動や変更の反映が速いのは、土台のViteの性質によります。Vite自体の仕組みは[Viteとは何かとVite 8.3の変更点を扱った記事](https://www.issoh.co.jp/tech/details/3587/)が参考になります。

## npm latestの1.6.4と公式サイトが案内する2.0 alphaの版の見分け方

VitePressを調べると、記事によって手順が微妙に違います。原因は、npmの既定版と公式サイトの説明が別の系列を指していることです。

### vitepressとvitepress@nextで入る版とNode.js要件の違い

2026年11月1日時点のnpm registryでは、`latest`タグが1.6.4、`next`タグが2.0.0-alpha.21（2026年10月25日公開）でした。`npm add -D vitepress`と打てば1.6.4が、`vitepress@next`と打てば2.0のalphaが入ります。

| 項目        | 1.6.4（latest） | 2.0.0-alpha.21（next） |
| --------- | ------------- | -------------------- |
| Node.js要件 | 18以上          | 22以上                 |
| 依存するVite  | 5.4系          | 8.3系                 |
| 依存するShiki | 2.1系          | 4.5系                 |
| 公式の手順書    | v1用の別サイト      | vitepress.dev本体      |

Node.jsの要件は、2.0系が[公式のGetting Started](https://vitepress.dev/guide/getting-started)で22以上、1.6系が[v1用のGetting Started](https://vuejs.github.io/vitepress/v1/guide/getting-started)で18以上です。検索で見つけた記事の手順を試す前に、どちらの系列を前提にしているかを確かめると、要件違いのエラーで時間を失いません。

### 2.0 alphaで続く破壊的変更とCHANGELOGで確認すべき項目

[CHANGELOG](https://github.com/vuejs/vitepress/blob/main/CHANGELOG.md)を読むと、2.0はalphaの段階で破壊的変更を重ねています。alpha.7でVite 7、alpha.18でVite 8へ上がり、同じalpha.18でNode.js 20の対応が外れました。alpha.19では`markdown.anchor`と`markdown.attrs`の設定の型が別プラグインへ移り、一部の項目名が変わっています。

日本語サイトに効く変更もあります。alpha.12から`markdown-it-cjk-friendly`が既定で有効になり、日本語の文中で`**強調**`が効かない問題への対処が入りました。1.6系で強調が崩れる箇所は、この変更で直る可能性があります。本番では1.6系を使い、2.0の正式版が[GitHubのリリース一覧](https://github.com/vuejs/vitepress/releases)に出た時点でCHANGELOGのBREAKING CHANGESを順に当てる進め方が安全です。

## npx vitepress initでの新規作成からローカル起動・ビルドまでの手順

ここからは手を動かす部分です。例は1.6系のlatestで書き、2.0で試す場合は`vitepress@next`に読み替えます。

### init ウィザードで作る雛形と.vitepressディレクトリの構成

公式手順では、パッケージを入れた後に`npx vitepress init`を実行し、対話形式で設定ファイルの置き場所やサイト名を答えます。`./docs`を選ぶと、次の4ステップで作成から本番用ビルドまで進みます。

```
# 1. 開発用依存として入れる（2.0を試すなら vitepress@next）
npm add -D vitepress

# 2. 対話形式で雛形を作る（設定の置き場所に ./docs を選ぶ）
npx vitepress init

# 3. 開発サーバーを起動する（http://localhost:5173 が開く）
npm run docs:dev

# 4. 本番用にビルドして確認する（docs/.vitepress/dist に出力、確認は 4173 番）
npm run docs:build
npm run docs:preview
```

ウィザードで「npmスクリプトを追加する」を選ぶと、`docs:dev`、`docs:build`、`docs:preview`の3つが`package.json`に入ります。設定ファイルは`docs/.vitepress/config.mts`、キャッシュは`.vitepress/cache`、成果物は`.vitepress/dist`に置かれます。キャッシュと成果物は`.gitignore`に入れておく対象です。

### ESM専用パッケージで起きるrequireエラーとtype moduleの設定

VitePressはESM専用のパッケージです。CHANGELOGによると1.0.0-rc.4でESMのAPIだけを提供する形になり、Getting Startedも`package.json`に`"type": "module"`を書くか、設定ファイルを`.mjs`か`.mts`にするよう求めています。

既存のリポジトリにドキュメントを足すときに、この点でつまずきます。アプリ本体がCommonJSのままだと、`package.json`全体を`"type": "module"`に変えられません。その場合は設定ファイルを`config.mts`で作り、ドキュメントだけをESMとして扱います。

## デフォルトテーマの拡張とVueコンポーネントで進めるカスタマイズ

VitePressのカスタマイズは、ゼロからテーマを作るより、既定のテーマを拡張する形が基本です。

### CSS変数の上書きとenhanceAppで登録する部品の書き方

[デフォルトテーマの拡張](https://vitepress.dev/guide/extending-default-theme)の手順では、`.vitepress/theme/index.ts`で既定テーマを`extends`し、色はCSS変数で上書きします。ブランド色の差し替えと、全ページで使う部品の登録は次の形です。

```
// docs/.vitepress/theme/index.ts
import type { Theme } from 'vitepress'
import DefaultTheme from 'vitepress/theme'
import ProductBadge from './ProductBadge.vue'
import './custom.css'

export default {
  extends: DefaultTheme,
  enhanceApp({ app }) {
    // Markdownのどこからでも <ProductBadge /> と書けるようにする
    app.component('ProductBadge', ProductBadge)
  }
} satisfies Theme

/* docs/.vitepress/theme/custom.css */
:root {
  --vp-c-brand-1: #0b5cad;
  --vp-c-brand-2: #2a74c4;
}
```

色の変更だけなら、この2ファイルで済みます。ロゴやナビゲーション、サイドバーの項目は`config.mts`の`themeConfig`で指定するため、テーマのコードには手を入れません。

### レイアウトスロットへの差し込みと内部部品の置き換えを避ける理由

本文の上にお知らせ枠を出したい、といった配置の変更には、`Layout`のスロットを使います。`doc-before`や`doc-top`は本文ページで、`layout-top`と`layout-bottom`は全ページで使えるスロットです。ラッパー部品で`Layout`を包み、該当するスロットへ中身を渡します。

Viteの`resolve.alias`で内部の部品を丸ごと差し替える方法もありますが、公式は内部部品の名前がマイナーリリースで変わりうると注意しています。2.0のalpha.5では`useSidebar`が削除されました。版を上げるたびに壊れる改造を避けるため、スロットとCSS変数で届かない要件が出た時点で、カスタムテーマへの切り替えを検討します。

## 日本語の全文検索とi18n設定で導入時に詰まりやすい箇所と回避策

検索と多言語化は、VitePressが標準で用意している範囲と、自前で補う範囲の境目を知っておく必要があります。

### provider localで動く日本語検索とIntl.Segmenterの分割

[検索のリファレンス](https://vitepress.dev/reference/default-theme-search)によると、`themeConfig.search.provider`に`'local'`を指定すると、MiniSearchを使ったブラウザ内の全文検索が有効になります。索引はビルド時に作られるため、外部サービスへの申請も通信も要りません。

```
// docs/.vitepress/config.mts（抜粋）
import { defineConfig } from 'vitepress'

export default defineConfig({
  lang: 'ja',
  title: '製品ドキュメント',
  base: '/product-docs/',
  themeConfig: {
    search: {
      provider: 'local',
      options: {
        locales: {
          root: {
            translations: {
              button: { buttonText: '検索', buttonAriaLabel: '検索' },
              modal: { noResultsText: '該当する結果がありません' }
            }
          }
        }
      }
    }
  }
})
```

同じリファレンスは、日本語と中国語の単語の分割に`Intl.Segmenter`を使うと書いています。非対応のブラウザでは単純な分割に戻るため、複数語の検索が一致しない場合があるという制約です。社内の古いブラウザで使われるサイトなら、`options.tokenize`で分割処理を差し替えるか、検索結果の確認を受け入れ試験に入れます。ページ数が数千規模になる場合や公開サイトでは、`provider: 'algolia'`でAlgolia DocSearchへ切り替える選択肢もあります。

### locales設定でルートの自動転送が起きない制約と公開時の対処

[i18nのガイド](https://vitepress.dev/guide/i18n)では、`docs/en/`のように言語ごとのディレクトリを作り、`locales`に`root`と各言語の`label`、`lang`を書きます。日本語を`root`、英語を`en`にする構成なら、既存の日本語ページのURLは変わりません。

注意点は2つあります。1つは、VitePressは`/`から`/en/`への自動転送をしないことです。ブラウザの言語に応じて振り分けたいなら、ホスティング側の設定で組みます。もう1つは、`themeConfig.algolia`を言語単位で上書きしてはいけないという制約で、Algoliaを使う場合も設定はサイト全体で1つにまとめます。

## GitHub Pages・CloudFrontへ公開するときのbase設定と配信先の注意

ビルド結果は静的ファイルなので、置き場所の選択肢は広くあります。設定を誤りやすいのは、サブパスに置くときの`base`です。

### base設定とGitHub Actionsで公開するworkflowの書き方

[デプロイのガイド](https://vitepress.dev/guide/deploy)によると、`https://example.github.io/repo/`に置くなら`base`は`'/repo/'`です。GitHub Pagesでは、リポジトリのSettingsにあるPagesでSourceを「GitHub Actions」に切り替え、次のようなworkflowを置きます。

```
# .github/workflows/deploy.yml（要点の抜粋）
name: Deploy VitePress site to Pages
on:
  push:
    branches: [main]
  workflow_dispatch:
permissions:
  contents: read
  pages: write
  id-token: write
concurrency:
  group: pages
  cancel-in-progress: false
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: actions/setup-node@v6
        with:
          node-version: 24
          cache: npm
      - run: npm ci
      - run: npm run docs:build
      - uses: actions/upload-pages-artifact@v3
        with:
          path: docs/.vitepress/dist
  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
    steps:
      - uses: actions/deploy-pages@v4
```

2.0系の公式の例はNode.js 24で、v1用の手順書の例はNode.js 20でビルドしています。1.6系で作る場合も、CIを2.0の要件（22以上）を満たす版にしておくと、2.0へ移るときにNode.jsの更新が要りません。GitLab Pagesに置く場合は、出力先の`outDir`を`../public`に変える必要があります。

### Netlifyの自動圧縮で起きるハイドレーションエラーとS3配信

同じガイドは、NetlifyなどでHTMLの自動圧縮（Auto Minify）を有効にすると、Vueが使うHTMLコメントが消えてハイドレーションのエラーが起きうると警告しています。配信サービス側のHTML圧縮は、VitePressのサイトでは切っておきます。

拡張子なしのURLにしたい場合の`cleanUrls: true`は、サーバー側で`.html`を補う設定が要ります。AWSで自社の管理下に置くなら、[CloudFrontとS3で静的サイトを公開する手順](https://www.issoh.co.jp/tech/details/18064/)で構成を作り、`cleanUrls`は既定のオフのまま始めると、URLの解決で迷いません。

## Docusaurus・MkDocsとの違いと受託開発で採用してよい条件・見送る場面

Markdownからドキュメントサイトを作るツールは複数あります。違いは機能の多寡より、カスタマイズするときに書く言語と、版の出し分けへの対応に出ます。

### VitePress・Docusaurus・MkDocsの土台と版の出し分けの比較

| ツール        | 土台            | 版の出し分け   | 標準の検索    |
| ---------- | ------------- | -------- | -------- |
| VitePress  | Vue 3・Vite    | 標準機能には無い | ローカル検索あり |
| Docusaurus | React・Node.js | 標準機能で対応  | 別途の導入が必要 |
| MkDocs     | Python        | 外部ツールで対応 | テーマ側で対応  |

VitePressの強みは、設定ファイル1行で日本語の検索まで動く手軽さと、Viteによる開発時の速さです。Next.jsで作ったサイトの配下に説明書を同居させたい場合は、[Nextraとは：Next.jsでドキュメントサイトを作る手順と既存サイトへの同居構成](https://www.issoh.co.jp/tech/details/19169/)が選択肢になります。Docusaurusの版管理と翻訳の仕組みは[Docusaurusの構築手順とバージョン管理・多言語・検索の設定](https://www.issoh.co.jp/tech/details/18707/)で、MkDocsは[Material for MkDocsの設定とGitHub Pages公開の手順](https://www.issoh.co.jp/tech/details/3675/)で扱っています。チームが書けるのがVueかReactかで迷う場合は、[ReactとVue 3の違いの比較](https://www.issoh.co.jp/tech/details/2348/)も判断材料になります。

### 製品ドキュメントでVitePressを採用してよい条件と見送る場面

採用してよいのは、版を1つに保つ製品ドキュメント、OSSやAPIの説明書、技術ブログを兼ねた開発者向けサイトです。Vueを触れる担当者が残るなら、テーマの拡張まで社内で回せます。

見送る場面ははっきりしています。第一に、利用者ごとに異なる版の説明書を読ませる必要がある製品。版の切り出しを自作すると、Docusaurusの`docs:version`に相当する仕組みを抱えることになります。第二に、原稿を書く人がGitを使えない組織。Markdownをリポジトリへコミットする前提を崩すと更新が止まり、ヘッドレスCMSや既存のWikiのほうが総コストは下がります。第三に、2.0の新機能を前提に本番を組む案件。alphaのうちは設定項目の名前が変わりうるため、正式版を待ちます。

### ドキュメントサイトと技術ブログを外部に委託する際の進め方と相談先

VitePressのサイトを外部に作らせる場合は、着手前に3点を決めておくと引き継ぎで揉めません。1.6系と2.0のどちらで作るか、検索をローカル検索で済ませるかAlgoliaに申請するか、公開先とURLの形（サブパスか、`cleanUrls`を使うか）です。どれも後から変えると、URLの構造か運用の手順が変わります。

技術ブログや製品のお知らせも同じサイトで出す、デザインを自社ブランドに合わせる、といった要件が重なると、CSS変数の上書きだけでは収まりません。当社では記事サイトや情報発信サイトの構築を[オウンドメディアサイト制作](https://www.issoh.co.jp/service/web/media/)として受託しており、ツールの選定から公開後の運用設計まで含めて相談いただけます。

## よくある質問

VitePressの導入検討でよく挙がる論点を、公式ドキュメントとnpm registryの記録をもとに整理します。

### VitePressを使うのにVue.jsの知識は必要ですか？

Markdownで原稿を書いて公開するだけなら、Vueの知識は要りません。既定のテーマのまま、ナビゲーションやサイドバーは設定ファイルに書くだけでサイトになります。原稿にVueコンポーネントを埋め込む、レイアウトのスロットへ独自の部品を差し込む、といった段階でVueを書ける人が要ります。

### VitePressは無料で商用利用できますか？

できます。ライセンスはMITで、公式サイトの表記は「Copyright © 2019-present Evan You」です。商用サイトでの利用や改変に制約はありません。費用が発生しうるのはツールの外側で、公開先のホスティング料金や、Algoliaの無料枠に当てはまらない場合の検索サービス料金が該当します。

### VitePressとVuePressはどちらを選ぶべきですか？

新規に作るならVitePressです。VuePress 1は公式に非推奨とされ、Vueチームは長期的に推奨するSSGとしてVitePressを挙げています。VuePress 2の開発を引き継いでいるのは、コミュニティのチームです。既定テーマのまま使っているVuePress 1のサイトなら、VitePressへの移行は比較的容易だと公式が案内しています。

### VitePressでブログを作ることはできますか？

作れます。公式は、ブログやポートフォリオ、マーケティングサイトも対象に挙げ、Vue.jsの公式ブログを例に示しています。記事一覧を組むのは、ビルド時にMarkdownを読み込むデータ読み込みの仕組みです。ただしブログ用のテーマは同梱されていないため、一覧ページやタグの画面は自分で作る前提です。Markdownで公開する方法の比較は[MarkdownでWebサイトを作る方法の選び方](https://www.issoh.co.jp/column/details/2566/)にまとめています。

### VitePress 2.0の正式版はいつ出ますか？

2026年11月1日時点で、正式版の公開日は公式に示されていません。npmの`next`タグは2.0.0-alpha.21で、alpha版は2025年11月から2026年10月までに8回公開されていました。正式版の時期を前提に計画を組まず、1.6系で作ってCIのNode.jsを22以上にしておく準備だけを先に済ませるのが無理のない進め方です。

## 関連記事

- [Docusaurusとは：ドキュメントサイトの構築手順とバージョン管理・多言語・検索の設定【3.10対応】](https://www.issoh.co.jp/tech/details/18707/)
- [Vite + Reactの環境構築手順｜Viteとは・Vite 8.3の変更点とTypeScript 7対応](https://www.issoh.co.jp/tech/details/3587/)
- [MkDocsとは？使い方とMaterial for MkDocsの設定・日本語検索・GitHub Pages公開【2026年版】](https://www.issoh.co.jp/tech/details/3675/)
- [SSGとは？静的サイトジェネレーターの仕組みと企業サイト採用の判断基準](https://www.issoh.co.jp/column/details/17699/)
- [CloudFrontとS3で静的サイトを公開する手順：OAC・独自ドメイン・デプロイまでCLIで構築](https://www.issoh.co.jp/tech/details/18064/)

---

出典: [VitePressとは：Vue製ドキュメントサイトの作り方と1.6系・2.0版の選び方【2026年11月版】](<https://www.issoh.co.jp/tech/details/19167/>)（株式会社一創）