はじめに
「ドキュメントサイトを作りたいけど、何を使えばいいの?」
この質問、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 -->
ここから本文が続きます...
<!-- 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対応 | 内蔵 | 内蔵 |
| 日本語情報 | 多い | 多い | 少なめ |
個人的には、Reactに慣れているならDocusaurus、Vueが好きならVitePress、非エンジニアも触るならGitBookという使い分けがいいと思います。
注意点
1. Reactの知識があると便利
カスタマイズしようとするとReactの知識が必要になります。Markdownだけで完結させるなら不要ですが、凝ったことをしたいなら学習コストがかかります。
2. ビルド時間
ドキュメントが増えるとビルド時間が長くなります。数百ページ規模になると数分かかることも。CI/CDのキャッシュ設定は必須です。
3. v3への移行
v2からv3への移行時に破壊的変更がありました。既存プロジェクトをアップグレードする場合は、公式の移行ガイドを確認してください。
まとめ
Docusaurusは「ドキュメントサイトを作りたい」という需要に対して、かなり完成度の高い解答を提供してくれます。
こんな場合におすすめです:
- OSSプロジェクトのドキュメントサイトを作りたい
- 社内ナレッジベースを構築したい
- Reactで自由にカスタマイズしたい
- バージョン管理や多言語対応が必要
- 検索機能が欲しい
30代になって思うのは、ドキュメントの重要性です。コードは書けても、ドキュメントがないと使ってもらえない。Docusaurusなら、ドキュメント作成のハードルを下げつつ、質の高いサイトが作れます。
まずは公式サイトのドキュメント(当然Docusaurusで作られている)を見てみてください。「あ、こういうサイトが作れるのか」とイメージが湧くと思います。
公式サイト: https://docusaurus.io GitHub: https://github.com/facebook/docusaurus ドキュメント: https://docusaurus.io/docs