2026.11.01 開発

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

Q: 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以上にしておく準備だけを先に済ませるのが無理のない進め方です。

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?によると、VitePressはMarkdownにテーマを当てて静的HTMLを書き出し、初回アクセスではそのHTMLを返します。読み込み後はVueのSPAとして動き、2ページ目以降はページ全体を読み直さずに本文だけを差し替える仕組みです。画面内に見えているリンク先は、先読みもしています。

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

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の変更点を扱った記事が参考になります。

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で22以上、1.6系がv1用のGetting Startedで18以上です。検索で見つけた記事の手順を試す前に、どちらの系列を前提にしているかを確かめると、要件違いのエラーで時間を失いません。

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

CHANGELOGを読むと、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のリリース一覧に出た時点で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で登録する部品の書き方

デフォルトテーマの拡張の手順では、.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の分割

検索のリファレンスによると、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のガイドでは、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://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で静的サイトを公開する手順で構成を作り、cleanUrlsは既定のオフのまま始めると、URLの解決で迷いません。

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

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

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

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

VitePressの強みは、設定ファイル1行で日本語の検索まで動く手軽さと、Viteによる開発時の速さです。Docusaurusの版管理と翻訳の仕組みはDocusaurusの構築手順とバージョン管理・多言語・検索の設定で、MkDocsはMaterial for MkDocsの設定とGitHub Pages公開の手順で扱っています。チームが書けるのがVueかReactかで迷う場合は、ReactとVue 3の違いの比較も判断材料になります。

製品ドキュメントで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変数の上書きだけでは収まりません。当社では記事サイトや情報発信サイトの構築をオウンドメディアサイト制作として受託しており、ツールの選定から公開後の運用設計まで含めて相談いただけます。

よくある質問

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

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

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

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

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

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

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

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

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以上にしておく準備だけを先に済ませるのが無理のない進め方です。