Docusaurus でドキュメントサイトを構築する

ライブラリ、フレームワーク、または SaaS 製品のドキュメントサイトが必要です。静的で高速、かつゼロから構築することなくメンテナンス可能なサイトが求められています。Docusaurus v3 はこれらを適切に処理します。これは成熟した React ベースの静的サイトジェネレーターで、バージョニング、検索統合、MDX サポートを標準で提供します。

このガイドでは、Docusaurus ドキュメントサイトのアーキテクチャと実践的なセットアップについて、マイナーリリース間で安定している概念に焦点を当てて説明します。

Docusaurus ドキュメントサイトのコアアーキテクチャ

Docusaurus はコンテンツを3つの異なるコンテンツタイプに分類します:

ドキュメントは /docs ディレクトリに配置されます。これらは主要なドキュメントページで、自動サイドバーナビゲーションとバージョニングサポートを備えてレンダリングされます。各 Markdown または MDX ファイルがページになります。

ブログ投稿は /blog に配置されます。これらは変更履歴、リリースアナウンス、または時間に敏感なチュートリアルに適しています。

ページは /src/pages にあり、カスタムランディングページ、概要セクション、またはドキュメント/ブログ構造外のあらゆるコンテンツ用のスタンドアロン React コンポーネントまたは MDX ファイルです。

サイドバーとバージョニングモデルには注意が必要です。Docusaurus はフォルダ構造からサイドバーを自動生成しますが、sidebars.js で明示的に定義することもできます。バージョンを作成すると、現在のドキュメントが versioned_docs/ にスナップショットされ、ユーザーは古いリリースのドキュメントにアクセスできます。

Docusaurus v3 セットアップ: 始め方

最新のスキャフォールディングは npm、Yarn、pnpm、Bun をサポートしています。チームが使用しているものを選択してください:

npx create-docusaurus@latest my-docs classic

classic プリセットは、ドキュメントプラグイン、ブログプラグイン、デフォルトテーマをバンドルしており、ほとんどの開発者向けドキュメントサイトに十分です。Docusaurus v3 は、ローカル開発と CI に Node.js 20 以降が必要です。

スキャフォールディング後、プロジェクト構造は次のようになります:

my-docs/
├── docs/
├── blog/
├── src/
│   ├── components/
│   ├── css/
│   └── pages/
├── static/
├── docusaurus.config.js
└── sidebars.js

docusaurus.config.js ファイルは、サイトメタデータ、テーマ設定、ナビゲーションバー、フッター、プラグインオプションを制御します。この単一ファイルで、React コードに触れることなくほとんどのカスタマイズを処理できます。

MDX ドキュメント: コンテンツの作成

Docusaurus v3 は MDX v3 を使用しており、以前のバージョンよりも厳格です。これは v2 から移行する場合に重要です。MDX v3 は適切な JSX 構文を強制し、不正な形式のコンポーネントを黙って無視しません。

各ドキュメントファイルは、メタデータ用のフロントマターをサポートしています:

---
id: getting-started
title: Getting Started
sidebar_position: 1
---

# Getting Started

Your content here. You can import React components directly.

React コンポーネントを直接埋め込んだり、Mermaid 図を使用したり、インタラクティブなコードブロックを含めることができます。@site エイリアスは、インポート用にプロジェクトルートを指します。

図を使用するには、設定で Mermaid プラグインを有効にします:

// docusaurus.config.js
module.exports = {
  markdown: {
    mermaid: true,
  },
  themes: ['@docusaurus/theme-mermaid'],
}

テーマとカスタマイズ

プラグインシステムにより、テーマをフォークすることなく機能を拡張できます。一般的なプラグインは、アナリティクス、サイトマップ、PWA サポート、リダイレクトを処理します。

ビジュアルカスタマイズには、src/css/custom.css で CSS 変数をオーバーライドします。テーマは内部で Infima を使用しているため、コンポーネントスタイルを書くのではなく、デザイントークンを調整します:

:root {
  --ifm-color-primary: #2e8555;
  --ifm-code-font-size: 95%;
}

より深いカスタマイズには「swizzling」を使用します。これはテーマコンポーネントを取り出して変更することです。npx docusaurus swizzle を実行して利用可能なコンポーネントを確認します。必要なものだけを swizzle してください。取り出されたコンポーネントは Docusaurus のアップグレード時に手動更新が必要になります。

検索統合

ほとんどの本番環境の Docusaurus サイトは Algolia DocSearch を使用しています。ドキュメントが公開されている場合は無料プログラムに申し込むか、プライベートドキュメントの場合はクローラーを自己ホストします。

設定は themeConfig に配置されます:

// docusaurus.config.js
module.exports = {
  themeConfig: {
    algolia: {
      appId: 'YOUR_APP_ID',
      apiKey: 'YOUR_SEARCH_API_KEY',
      indexName: 'YOUR_INDEX_NAME',
    },
  },
}

DocSearch v4 は Algolia AskAI もサポートしており、標準検索エクスペリエンスの上にオプションの対話型検索を追加し、同じ Algolia 統合の一部として設定されます。

デプロイ

Docusaurus は /build ディレクトリに静的な HTML、CSS、JavaScript をビルドします。Vercel、Netlify、GitHub Pages、Cloudflare Pages、または独自の CDN など、あらゆる静的ホスティングが機能します。

npm run build

出力は、サーバーランタイムを必要としない標準的な静的サイトです。不明なパスに対して index.html を提供することで、クライアントサイドルーティングを処理するようにホスティングプロバイダーを設定します。

本番環境で知っておくべきこと

開発者向けドキュメントサイトをメンテナンスするための実践的な注意点:

• バージョニングは複雑さを増します。 ユーザーが本当に古いドキュメントへのアクセスを必要とする場合にのみバージョニングを使用してください。多くのプロジェクトは単一の「現在」バージョンで問題ありません。
• MDX の厳格さは実際のバグを検出します。 v2 からの移行でページが壊れた場合、エラーは通常、修正する価値のある実際の JSX 問題を指摘しています。
• ビルド時間はコンテンツに応じてスケールします。 大規模なサイトは、CI でのインクリメンタルビルドと node_modules のキャッシュから恩恵を受けます。

まとめ

Docusaurus はインフラストラクチャを処理するため、優れたドキュメントの作成に集中できます。React 基盤により、フロントエンドチームは必要に応じて深くカスタマイズできますが、デフォルトは十分に機能するため、多くのサイトは React コードに全く触れることなく出荷されます。classic プリセットから始め、要件が現れたらプラグインを追加し、ドキュメントコンテンツが充実する前に過度なカスタマイズをしたいという衝動に抵抗してください。

よくある質問

Gain Debugging Superpowers

Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers. Check our GitHub repo and join the thousands of developers in our community.