VuePressはもう終わったのか、v2の今を確かめてみた

はじめに

VuePressのGitHubリポジトリを開くと、READMEの一番目立つところにこう書いてあります。

VuePress v1 is now in maintenance mode.

「メンテナンスモード」――つまり新機能は追加せず、最低限の保守だけを続ける状態です。これを見て「もう終わったツールなんだな」と静かにタブを閉じた人も多いのではないでしょうか。VuePressの後継としてVitePressが華々しく紹介される記事も増えていますし、なおさらそう思えます。

ただ、実際にリポジトリを追ってみると話はそう単純ではありませんでした。「v1」が保守モードなだけで、コミュニティ主導の「v2」は今この瞬間も機能追加が続いているのです。今回はVuePressというツールそのものの特徴と、v1・v2という2つの現在地を整理しながら使い方を解説します。

VuePressとは

VuePressは、Vue.jsを使って構築された静的サイトジェネレーター（SSG）です。Markdownファイルを中心にコンテンツを書き、それをVueベースの単一ページアプリケーション（SPA）として事前レンダリングします。Vue.jsの作者であるEvan You氏が開発を始め、公式ドキュメントサイトのビルドツールとして採用されたことでも知られています。

主な特徴

• Markdown中心の執筆体験 - フロントマターと見出しだけでページが作れ、執筆に集中できる
• MarkdownにVueコンポーネントを埋め込める - <Badge /> のような独自コンポーネントや {{ }} の式展開がMarkdown内でそのまま使える
• デフォルトテーマとプラグインエコシステム - 検索・多言語対応・カスタムコンテナなどをプラグインで拡張できる
• 複数バンドラーに対応 - v2ではViteとWebpackのどちらでもビルドできる

VuePressの「今」— v1とv2という2つの現在地

VuePressには互換性のない2つの世代が存在します。

• v1（Vue 2ベース）: 公式にメンテナンスモード入りが宣言されており、新機能は追加されません。npmのlatestタグは今もこのv1（1.9.10）を指しています
• v2（Vue 3ベース、Vite/Webpack対応）: コミュニティが開発を引き継ぎ、vuepress/coreというリポジトリで今も活発にコミットが続いています。ただし執筆時点でもバージョンは2.0.0-rc.31と、長らくリリース候補（RC）のままです

つまり「VuePressはもう終わった」わけではなく、「安定版として長く使われてきたv1が保守モードに入り、開発の主戦場がv2に移った」というのが正確なところです。これから新規に使うなら、開発が続いているv2を選ぶのが基本になります。

インストール

Node.js v20.9.0以上が必要です。v2はnpmのnextタグで配布されているため、インストール時にバージョン指定が必要です。

mkdir vuepress-starter && cd vuepress-starter
npm init -y

# v2（開発が続いているバージョン）を入れる場合
npm i -D vuepress@next vue
npm i -D @vuepress/bundler-vite@next @vuepress/theme-default@next

v1をそのまま使いたい場合はバージョン指定なしでインストールできますが、前述のとおり新機能は追加されない点に注意してください。

# v1（メンテナンスモード）を入れる場合
npm i -D vuepress

docsディレクトリと設定ファイルを作成します。

mkdir -p docs/.vuepress
echo '# Hello VuePress' > docs/README.md

package.jsonにスクリプトを追加します。

{
  "scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"
  }
}

基本的な使い方

docs/.vuepress/config.jsにサイト全体の設定を書きます。titleはナビバーに、descriptionはメタタグとして使われます。

// docs/.vuepress/config.js
import { defineUserConfig } from 'vuepress'
import { viteBundler } from '@vuepress/bundler-vite'
import { defaultTheme } from '@vuepress/theme-default'

export default defineUserConfig({
  lang: 'ja-JP',
  title: 'My Docs',
  description: 'VuePressで作るドキュメントサイト',
  bundler: viteBundler(),
  theme: defaultTheme({
    navbar: [
      { text: 'ホーム', link: '/' },
      { text: 'ガイド', link: '/guide/' },
    ],
  }),
})

npm run docs:devで開発サーバーが起動し、Markdownを保存するたびにホットリロードされます。npm run docs:buildを実行するとdocs/.vuepress/distに静的HTMLが出力され、そのままどのホスティングサービスにもデプロイできます。

実践的なユースケース

MarkdownにVueコンポーネントを埋め込む

VuePress最大の特徴は、素のMarkdownの中にVueのテンプレート構文やコンポーネントをそのまま書けることです。フロントマターでページごとのメタ情報も指定できます。

---
title: サンプルページ
---

# {{ 1 + 1 }} という式もそのまま評価されます

<Badge text="beta" type="warning" />

<CustomAlert v-if="isImportant">
  重要なお知らせです
</CustomAlert>

.vuepress/theme や .vuepress/components 以下に置いた.vueファイルは自動的にグローバルコンポーネントとして登録され、どのMarkdownからも呼び出せるようになります。

カスタムコンテナで注釈を目立たせる

APIドキュメントや手順書では「注意」「警告」を目立たせたい場面が多くあります。VuePressは:::で囲むだけでTip・Warning・Dangerのボックスを作れるカスタムコンテナ記法を標準サポートしています。

::: tip ヒント
デフォルトテーマではこのまま緑色のボックスとして表示されます。
:::

::: warning 注意
破壊的変更を含むバージョンアップ前には必ずお読みください。
:::

::: danger 危険
このコマンドはビルド成果物をすべて削除します。
:::

見出しや文中に埋もれがちな注意書きを、視覚的に分離できるのがポイントです。tipをdetailsに変えると折りたたみ可能な補足欄にもなります。

テーマとプラグインで見た目と機能を拡張する

VuePressはデフォルトテーマだけでなく、サードパーティ製テーマやプラグインをconfig.jsに追加していく形で拡張します。検索・SEO・目次生成などはプラグインとして提供されています。

import { defineUserConfig } from 'vuepress'
import { searchPlugin } from '@vuepress/plugin-search'

export default defineUserConfig({
  theme: defaultTheme({
    sidebar: 'auto',
    logo: '/logo.png',
  }),
  plugins: [
    searchPlugin({
      maxSuggestions: 10,
    }),
  ],
})

plugins配列に追加するだけでサイト内検索やページ内目次などの機能が有効になるため、必要な機能だけを選んで軽量に保てます。

多言語対応（i18n）でサイトを国際化する

localesオプションを使うと、パスごとに異なる言語・タイトル・説明文を割り当てられます。ナビバーや検索窓の文言もロケールに応じて切り替わります。

export default defineUserConfig({
  locales: {
    '/': {
      lang: 'en-US',
      title: 'My Docs',
      description: 'Documentation site powered by VuePress',
    },
    '/ja/': {
      lang: 'ja-JP',
      title: 'マイドキュメント',
      description: 'VuePressで作るドキュメントサイト',
    },
  },
})

/ja/配下にMarkdownを配置すれば、URLパスに応じて言語が切り替わる多言語サイトがそのまま出来上がります。

まとめ

VuePressは「終わったツール」ではなく、「役割が分かれたツール」だと捉えるのが正確です。安定運用してきたv1はメンテナンスモードとして役目を終えつつありますが、その設計思想を引き継いだv2はコミュニティの手で今も開発が続いています。

Vue.js公式が推すVitePressとどちらを選ぶか迷う場面もあると思いますが、Webpackを使い続けたい既存プロジェクトや、豊富なv1時代のプラグイン資産を活かしたい場合には、VuePress v2も十分に検討候補になります。まずはvuepress@nextで小さなdocsサイトを立ち上げて、Markdown中心の執筆体験を試してみてください。

参考リンク

• VuePress公式ドキュメント
• VuePress GitHub
• vuepress - npm
• Vuepress GitHub