ドキュメントがプロジェクトの成否を分ける理由
優れたコードであっても、動かし方がわからなければ意味がありません。GitHubで素晴らしいライブラリが、単に「スタートガイド」が読みづらいテキストの塊だったという理由だけで埋もれていくのを何度も見てきました。ロジックを書くことは仕事の半分に過ぎません。残りの半分は、チームメンバーや将来の自分がセットアップの問題で時間を無駄にしないよう、そのロジックを説明することです。私の経験上、高品質なドキュメントこそが、週末の趣味プロジェクトとプロフェッショナルなツールの境界線となります。
Docusaurusはそのためのソリューションとして、私が最も好んでいるツールです。Metaによって開発されたこの静的サイトジェネレーターは、Reactを活用して高速で検索性が高く、美しいサイトを作成します。フロントエンドのエキスパートである必要はありません。ルーティングやバージョニングといった複雑な部分はDocusaurusが処理してくれるため、ユーザーはシンプルなMarkdownを書くだけで済みます。このガイドでは、5分以内にサイトを立ち上げ、デプロイパイプライン全体を自動化する方法を紹介します。
クイックスタート（5分でセットアップ）
まず、Node.js（バージョン18.0以降）がマシンにインストールされていることを確認してください。ターミナルで node -v と入力すれば、現在のバージョンを確認できます。
1. プロジェクトの初期化
次のコマンドを実行して、標準の「classic」テンプレートを使用した新しいサイトを作成します。これにはランディングページ、ブログ、ドキュメントエンジンが含まれています。
npx create-docusaurus@latest my-docs classicこれにより my-docs というディレクトリが作成されます。インストールが完了したら、そのフォルダに移動します。
cd my-docs2. 開発サーバーの起動
ローカルプレビューを起動して、変更をリアルタイムで確認しましょう。
npm startブラウザで自動的に http://localhost:3000 が開くはずです。これで、ダークモード、検索バー（プレースホルダー）、レスポンシブデザインを標準装備した機能的なサイトが手に入りました。
基本構造：コンテンツの配置場所
Docusaurusは、サイトを特定のゾーンに分けることで整理を保ちます。このレイアウトを理解しておけば、後でファイルを探し回る手間が省けます。
/docs: サイトの心臓部です。ここにあるすべてのMarkdownファイルが自動的にページになります。/blog: 変更履歴やプロジェクトのアップデートに最適です。docusaurus.config.js: コントロールセンターです。サイトのタイトル、SNSリンク、SEOメタデータの更新に使用します。sidebars.js: ページの順序を決定します。チュートリアルに特定の流れを持たせたい場合は、ここで定義します。
MDXによるMarkdownの拡張
DocusaurusはMDXを使用しており、Markdownファイル内にReactコンポーネントを直接埋め込むことができます。これは重要な情報を強調する際に非常に便利です。プレーンテキストの代わりにAdmonitions（注釈）を使って読者の注意を引きましょう。
:::tip プロのヒント
サイトのSEOを向上させるために、'setup.md' ではなく 'authentication-setup.md' のような説明的なファイル名を使用しましょう。
:::サイドバーの制御
Docusaurusはサイドバーを自動生成できますが、手動で設定したほうがユーザーエクスペリエンスは向上します。sidebars.js を開いて、読者のための論理的な階層を作成しましょう。
module.exports = {
mySidebar: [
'intro',
{
type: 'category',
label: '基本コンセプト',
items: ['api-basics', 'authentication'],
},
],
};CI/CDによるすべてを自動化
サーバーへのファイルの手動アップロードはミスの原因になります。GitHub Actionsを使用すれば、main ブランチにコードをプッシュした瞬間にドキュメントが更新されます。
1. 本番用URLの設定
Docusaurusに対し、ウェブ上のどこに配置されるかを伝える必要があります。docusaurus.config.js を開き、以下の行を自身のGitHubの詳細に合わせて更新してください。
const config = {
title: 'プロジェクトドキュメント',
url: 'https://<your-username>.github.io',
baseUrl: '/my-docs/',
organizationName: '<your-username>',
projectName: 'my-docs',
trailingSlash: false,
// ...
};2. GitHub Action of the creation
.github/workflows/deploy.yml にファイルを作成します。このスクリプトは、変更をプッシュするたびにビルドプロセスを自動化します。依存関係のインストールを処理し、最終的なHTMLを gh-pages ブランチにプッシュします。
name: GitHub Pagesへのデプロイ
on:
push:
branches: [main]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
cache: 'npm'
- name: インストールとビルド
run: |
npm install
npm run build
- name: デプロイ
uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./buildユーザーエクスペリエンスを向上させるプロのヒント
何十ものドキュメントサイトを構築してきた経験から、細かなディテールがユーザーの満足度に大きく影響することに気づきました。
インスタント検索の追加
ユーザーに答えを探させないようにしましょう。DocusaurusはAlgolia DocSearchとシームレスに統合できます。サイトが公開されたら、無料枠に申し込みましょう。コンテンツをインデックス化し、100ミリ秒以下で結果を返す超高速な検索インターフェースを提供してくれます。
ドキュメントのバージョン管理
メジャーアップデート（v1からv2への移行など）をリリースする場合、古いドキュメントを消去してはいけません。Docusaurusのバージョニングツールを使用しましょう。ナビゲーションバーにバージョン選択のドロップダウンが追加され、ユーザーが実際に使用しているソフトウェアのバージョンに合わせたドキュメントを選択できるようになります。
シンプルに保つ
ダラダラと長い文章は避けましょう。npm install のような単純なコマンドであっても、すべてのコマンドにコードブロックを使用してください。ユーザーが前提手順を知っていると思い込んではいけません。基礎から丁寧にドキュメント化することで、後で対応しなければならないサポートチケットやGitHubのIssueの数を減らすことができます。
