Docusaurus - Metaが作ったドキュメントサイト生成ツールの実力

はじめに

「ドキュメントサイトを作りたいけど、何を使えばいいの？」

この質問、30代エンジニアなら一度は考えたことがあるんじゃないでしょうか。

Docusaurusは、Meta（旧Facebook）が開発したドキュメントサイト生成ツールです。GitHubでは62,900スター以上を獲得しており、Redux、Supabase、Testing Libraryなど、名だたるOSSプロジェクトが採用しています。

個人的には「ドキュメントサイトを作るならこれ一択」と言えるくらい、完成度が高いツールだと思います。セットアップは簡単だし、Reactベースで拡張性もある。何より、コンテンツに集中できるんですよね。

Docusaurusとは

Docusaurusは、オープンソースプロジェクトのウェブサイト構築・デプロイ・保守を簡素化するために生まれた静的サイトジェネレーターです。

コンセプトは**「Build optimized websites quickly, focus on your content」**。最適化されたウェブサイトを素早く構築し、コンテンツに集中する。この思想がツール全体に反映されています。

主な特徴：

Reactベース: Reactコンポーネントで自由にカスタマイズ可能
MDX対応: MarkdownにReactコンポーネントを埋め込める
バージョン管理: ドキュメントのバージョニングが標準機能
多言語対応: i18nが組み込まれている
検索機能: Algolia DocSearchをサポート

公式サイト: https://docusaurus.io GitHub: https://github.com/facebook/docusaurus

特徴・メリット

1. セットアップが圧倒的に簡単

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

npx create-docusaurus@latest my-website classic
cd my-website
npm run start

たった3コマンドで、ドキュメントサイトの雛形が立ち上がります。classicテンプレートには、ドキュメント、ブログ、カスタムページ、CSSフレームワーク（ダークモード対応）が全部入っています。

正直なところ、ゼロからNext.jsでドキュメントサイトを作ろうとしたら、この状態に持っていくだけで数日かかりますからね。時短になります。

2. MDXでReactコンポーネントが使える

普通のMarkdownじゃ物足りないときってありますよね。インタラクティブなデモを入れたいとか、カスタムUIを差し込みたいとか。

DocusaurusはMDX対応なので、Markdownの中にReactコンポーネントを埋め込めます。

---
title: My Page
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# インストール方法

<Tabs>
  <TabItem value="npm" label="npm">
    ```bash
    npm install my-library
    ```
  </TabItem>
  <TabItem value="yarn" label="yarn">
    ```bash
    yarn add my-library
    ```
  </TabItem>
</Tabs>

タブ切り替えUIがMarkdown内で使えます。技術ドキュメントでよくある「npm/yarn/pnpmのインストールコマンドを切り替える」やつ、簡単に実装できます。

3. ドキュメントのバージョン管理

OSSプロジェクトを運営していると、「v1のドキュメントも残しておきたいけど、v2のドキュメントも公開したい」という状況になります。

Docusaurusはこれが標準機能です。

npm run docusaurus docs:version 1.0

このコマンド一発で、現在のドキュメントをv1.0としてスナップショット保存できます。ユーザーはサイト上でバージョンを切り替えて閲覧できます。

地味だけど、これがないと結構困るんですよね。

4. 多言語対応が組み込み

国際的なプロジェクトなら、ドキュメントの多言語化は必須です。Docusaurusにはi18n機能が最初から入っています。

// docusaurus.config.js
module.exports = {
  i18n: {
    defaultLocale: 'ja',
    locales: ['ja', 'en', 'zh-hans'],
  },
};

CrowdInとの連携もサポートされているので、翻訳ワークフローもスムーズに構築できます。

5. Algolia DocSearchで検索機能

ドキュメントが増えてくると、検索機能が欲しくなります。DocusaurusはAlgolia DocSearchとの連携が組み込まれています。

OSSプロジェクトなら無料で使えるので、コスパ的にもいい。検索UXは本当に重要で、これがあるとないとでドキュメントの使い勝手が全然違います。

6. プラグインアーキテクチャ

「標準機能じゃ足りない」という場合も、プラグインで拡張できます。

サイトマップ生成
Google Analytics連携
PWA対応
カスタムページ追加

など、公式・コミュニティプラグインが豊富です。

インストール方法

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

新規プロジェクト作成

npx create-docusaurus@latest my-website classic

TypeScriptを使いたい場合：

npx create-docusaurus@latest my-website classic --typescript

ディレクトリ構造

my-website/
├── blog/              # ブログ記事
├── docs/              # ドキュメント
├── src/
│   ├── components/    # Reactコンポーネント
│   ├── css/           # スタイル
│   └── pages/         # カスタムページ
├── static/            # 静的ファイル
├── docusaurus.config.js
├── package.json
└── sidebars.js        # サイドバー設定

開発サーバーの起動

cd my-website
npm run start

ブラウザでhttp://localhost:3000が自動的に開きます。

ビルド

npm run build

/buildディレクトリに静的ファイルが生成されます。これをそのままホスティングサービスにデプロイできます。

基本的な使い方

ドキュメントの追加

docs/ディレクトリにMarkdownファイルを追加するだけです。

---
sidebar_position: 1
---

# はじめに

このドキュメントでは、プロジェクトの概要を説明します。

## インストール

```bash
npm install my-library

基本的な使い方

...


`sidebar_position`でサイドバーの表示順を制御できます。

### サイドバーのカスタマイズ

```javascript
// sidebars.js
module.exports = {
  tutorialSidebar: [
    'intro',
    {
      type: 'category',
      label: 'チュートリアル',
      items: ['tutorial-basics/create-a-document', 'tutorial-basics/create-a-page'],
    },
    {
      type: 'category',
      label: 'API リファレンス',
      items: ['api/overview', 'api/methods'],
    },
  ],
};

階層構造も自由に作れます。

ブログ記事の追加

blog/ディレクトリにMarkdownファイルを追加します。

---
slug: welcome
title: ようこそ
authors: [easegis]
tags: [お知らせ]
---

プロジェクトのブログを始めました。

<!-- truncate -->

ここから本文が続きます...

で一覧表示時の抜粋位置を指定できます。

設定ファイル

// docusaurus.config.js
module.exports = {
  title: 'My Project',
  tagline: 'プロジェクトの説明',
  url: 'https://myproject.com',
  baseUrl: '/',
  onBrokenLinks: 'throw',
  onBrokenMarkdownLinks: 'warn',
  favicon: 'img/favicon.ico',

  presets: [
    [
      'classic',
      {
        docs: {
          sidebarPath: require.resolve('./sidebars.js'),
          editUrl: 'https://github.com/myorg/myproject/tree/main/',
        },
        blog: {
          showReadingTime: true,
        },
        theme: {
          customCss: require.resolve('./src/css/custom.css'),
        },
      },
    ],
  ],

  themeConfig: {
    navbar: {
      title: 'My Project',
      logo: {
        alt: 'Logo',
        src: 'img/logo.svg',
      },
      items: [
        { to: '/docs/intro', label: 'Docs', position: 'left' },
        { to: '/blog', label: 'Blog', position: 'left' },
        {
          href: 'https://github.com/myorg/myproject',
          label: 'GitHub',
          position: 'right',
        },
      ],
    },
    footer: {
      style: 'dark',
      copyright: `Copyright © ${new Date().getFullYear()} My Project.`,
    },
  },
};

実践的なユースケース

1. OSSプロジェクトのドキュメントサイト

これが王道の使い方です。

# プロジェクト作成
npx create-docusaurus@latest my-oss-docs classic --typescript

# バージョン管理設定
npm run docusaurus docs:version 1.0.0

# GitHub Pages へデプロイ
npm run build
npm run deploy

APIリファレンス、チュートリアル、FAQ、変更履歴をまとめて管理できます。

2. 社内ナレッジベース

社内の技術ドキュメントをDocusaurusで管理している会社も増えています。

新人エンジニア向けオンボーディング資料
技術選定の意思決定ログ
トラブルシューティングガイド
社内ライブラリのAPIドキュメント

検索機能があるので、「あの情報どこだっけ」が減ります。

3. 技術ブログ

Docusaurusはブログ機能も持っているので、技術ブログとしても使えます。

---
slug: react-19-new-features
title: React 19の新機能まとめ
authors: [yourname]
tags: [React, JavaScript, フロントエンド]
---

React 19がリリースされました。今回は主要な新機能を紹介します。

<!-- truncate -->

## Server Components

...

ドキュメントとブログを同じサイトで運営できるのは便利です。

4. カスタムランディングページ

Reactコンポーネントでカスタムページを作れるので、プロダクトのランディングページも作れます。

// src/pages/index.js
import React from 'react';
import Layout from '@theme/Layout';
import Link from '@docusaurus/Link';

export default function Home() {
  return (
    <Layout title="Home">
      <main>
        <div className="hero">
          <h1>My Awesome Project</h1>
          <p>プロジェクトの説明文がここに入ります</p>
          <Link to="/docs/intro" className="button">
            ドキュメントを読む
          </Link>
        </div>
      </main>
    </Layout>
  );
}

デプロイ

GitHub Pages

# docusaurus.config.jsに設定追加
module.exports = {
  url: 'https://username.github.io',
  baseUrl: '/my-project/',
  organizationName: 'username',
  projectName: 'my-project',
  deploymentBranch: 'gh-pages',
};

GIT_USER=<GITHUB_USERNAME> npm run deploy

Vercel / Netlify

そのままデプロイできます。ビルドコマンドはnpm run build、出力ディレクトリはbuildを指定するだけ。

Cloudflare Pages

Cloudflare Pagesでも問題なく動きます。個人的にはCloudflare Pagesがコスパ的におすすめですね。

他のツールとの比較

「Docusaurus以外にも選択肢あるよね？」という話。

項目	Docusaurus	VitePress	GitBook
技術基盤	React	Vue	独自
学習コスト	低〜中	低	低
カスタマイズ性	高い	中程度	低い
バージョン管理	標準対応	プラグイン	有料版のみ
検索機能	Algolia対応	内蔵	内蔵
日本語情報	多い	多い	少なめ