【完全入門】Docusaurusの使い方完全ガイド｜Markdownで技術ドキュメント・マニュアルサイトを構築する手順

ソフトウェアの仕様書やAPIリファレンス、社内マニュアル、オープンソース（OSS）プロジェクトのドキュメントを作成・運用する際、「WordやExcelでのマニュアル管理に限界を感じている」「GitでMarkdown文書をバージョン管理し、美しく見やすいWebサイトとして自動公開したい」「Reactのコンポーネントを埋め込んだり、デザインを柔軟にカスタマイズしたい」といった要望を持つ開発チームが急速に増えています。

そんな課題を完璧に解決する世界標準の静的サイトジェネレーターが、Meta（旧Facebook）社によって開発されたオープンソースツール「Docusaurus（ドキュサウルス）」です。

Docusaurusを採用すれば、普段使い慣れているMarkdown（.md）やMDX（.mdx）で記事を書くだけで、Googleのように軽快な検索機能、美しいシンタックスハイライト、ダークモード切り替え、多言語（i18n）対応、ドキュメントのバージョン管理機能を備えた本格的なWebサイトが最短5分で立ち上がります。さらにGitHub PagesやGitHub Actionsと連携することで、Gitにプッシュするだけで最新サイトが自動公開される運用基盤が完全無料で手に入ります。

本記事では、Docusaurusの基本概念や他の静的サイトジェネレーター（MkDocs、Docsify）との比較から、インストール・初期セットアップ、Markdown/MDXの基本操作、Mermaid図解の埋め込み、サイトデザインのカスタマイズ、そしてGitHub Pagesでの自動デプロイ手順まで、ステップ形式で分かりやすく完全解説します！

Docusaurusとは？Markdownで美しいドキュメントサイトを高速構築できる3つの理由

Docusaurus（ドキュサウルス）とは、ReactとNode.jsをベースに開発された、ドキュメント特化型の静的サイトジェネレーター（Static Site Generator: SSG）です。Meta社のオープンソースチームが中心となって開発・メンテナンスを行っており、React公式ドキュメント、React Native、Jest、Reduxなど、世界中の巨大な開発者コミュニティや企業の技術サイトで標準採用されています。

テキストエディタで書いたMarkdownファイルを指定のディレクトリに配置するだけで、レスポンシブ対応・SEO最適化・超高速な静的HTMLサイトへと自動ビルドしてくれます。

MkDocsやDocsifyとの違い・比較表（React/MDX対応・パフォーマンス・検索性）

技術ドキュメントを作成するための代表的な静的サイトジェネレーターには、Docusaurusのほかに「MkDocs」や「Docsify」などがあります。それぞれのツールが持つ特性を以下の比較表で整理しました。

Python環境で手軽に作りたい場合はMkDocsがおすすめです。導入が極めてシンプルで設定ファイル1つで完成度の高いサイトが立ち上がります。詳しい導入手順については、当サイトの解説記事 【完全入門】MkDocsの使い方完全ガイド｜Materialテーマ導入・日本語検索設定とGitHub Pages公開手順 をあわせてご覧ください。

一方、「ReactのUIコンポーネントをドキュメント内に直接埋め込みたい」「ドキュメントの過去バージョン（v1.0、v2.0など）の切り替えドロップダウンを標準機能で運用したい」「将来的に多言語展開（英語・日本語）を行いたい」という場合には、Docusaurusが圧倒的な優位性を誇ります。

開発者・企業のマニュアル作成で選ばれる理由

世界中の開発現場でDocusaurusが選ばれ続けている理由は、ドキュメント運用で直面するあらゆる課題を先回りして解決する以下の3点に集約されます。

【5分で完了】Docusaurusのインストールと初期セットアップ手順

ここからは、実際に手元のパソコンにDocusaurusをインストールし、ローカル環境で初期サイトを立ち上げるまでの手順を解説します。

前提条件（Node.js環境の確認）

Docusaurusを動作させるには、パソコンにNode.js 18.0以上がインストールされている必要があります。ターミナル（macOS / Linux）またはPowerShell / コマンドプロンプト（Windows）を開き、以下のコマンドでバージョンを確認してください。

node -v
npm -v

実行結果として v18.0.0 以上の数値が表示されれば準備完了です。もしNode.jsが未インストールの場合は、Node.js公式サイトから推奨版（LTS版）をダウンロードしてインストールしてください。

npx create-docusaurus コマンドによるプロジェクト作成

Docusaurusには公式の対話型スキャフォールディングツールが用意されています。以下のコマンドを実行することで、推奨テンプレート（classic）が設定されたプロジェクトが一瞬で自動生成されます。

# my-website はお好みのプロジェクト名に変更可能
npx create-docusaurus@latest my-website classic

※TypeScriptで運用したい場合は、末尾に --typescript を付与して実行してください：

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

実行が完了すると、my-website というディレクトリが作成され、その中に以下の主要ファイル・フォルダが展開されます。

my-website/
├── blog/                  # ブログ記事用のMarkdownファイルを格納
├── docs/                  # ★技術ドキュメントのMarkdownファイルを格納
├── src/                   # カスタムReactコンポーネントやトップページ用ファイル
│   ├── css/custom.css     # サイト全体のカスタムスタイル（カラー設定等）
│   └── pages/index.js     # トップページのReactコード
├── static/                # ロゴ画像や静的アセットを配置するフォルダ
├── docusaurus.config.js   # ★サイト全体の設定ファイル（最重要）
├── sidebars.js            # ★サイドバーのメニュー構造を定義する設定ファイル
└── package.json           # プロジェクトの依存関係とスクリプト一覧

日常的な執筆作業では、主に docs/ ディレクトリ配下のMarkdownファイルの作成 と、必要に応じた docusaurus.config.js の編集 だけで運用が完結します。

ローカル開発サーバーの起動（npm run start）と画面確認

プロジェクトフォルダへ移動し、ローカル開発サーバーを立ち上げましょう。

cd my-website
npm run start

コマンドを実行すると自動的にブラウザが起動し、http://localhost:3000/ で洗練されたDocusaurusの初期ウェルカムサイトが表示されます。

Docusaurusの基本操作とMarkdown/MDXページの作成方法

Docusaurusの最大の特徴は、一般的なMarkdownファイル（.md）に加えて、ReactのJSX構文を混在できるMDXファイル（.mdx）を標準でサポートしている点です。

docsディレクトリの構造とサイドバー自動生成（sidebars.js）

ドキュメントページを追加するには、docs/ フォルダの中にMarkdownファイルを配置するだけです。階層構造を持たせたい場合は、サブディレクトリを作成してその中にファイルを整理します。

docs/
├── intro.md               # はじめに（トップドキュメント）
├── tutorial-basics/       # 基礎チュートリアル（カテゴリフォルダ）
│   ├── _category_.json    # カテゴリの表示名や順序を設定するファイル
│   ├── create-a-page.md
│   └── deploy.md
└── guides/                # 実践ガイド
    ├── api-reference.md
    └── troubleshooting.md

初期状態の sidebars.js では、サイドバー自動生成機能（Autogenerated Sidebar）が有効になっています。

// sidebars.js
const sidebars = {
  tutorialSidebar: [{ type: 'autogenerated', dirName: '.' }],
};

module.exports = sidebars;

この設定にしておけば、docs/ 配下のフォルダ構造とファイル名がそのまま左側のサイドバーメニューとして自動反映されます。新しいページを追加するたびにメニュー定義を手動編集する必要がないため、大規模なドキュメントでも破綻せずに運用できます。

Markdown記法とFrontmatter（title, id, sidebar_position）の設定

Markdownファイルの最上部には、ページ固有のメタデータを定義するFrontmatter（フロントマター）を記述します。ハイフン3つ（---）で囲んでYAML形式で指定します。

---
id: getting-started
title: 初めてのセットアップガイド
sidebar_label: クイックスタート
sidebar_position: 1
slug: /getting-started
description: Docusaurusの初期設定から起動までの手順を解説します
---

# 初めてのセットアップガイド

ここから記事本文を執筆します。

Docusaurusで使えるMarkdown構文一覧（見出し、リスト、太字、引用、テーブルなど）については、当サイトの完全ガイド 【コピペで使える】Markdown記法一覧・チートシート｜基本の書き方から応用・早見表まで完全網羅 を手元に置いて確認しながら記述してください。

Mermaid記法によるフローチャート・シーケンス図の埋め込み

技術仕様書やインフラ設計書を作成する際、アーキテクチャ図やシーケンス図をテキストで記述できる「Mermaid（マーメイド）」は欠かせない機能です。

Docusaurusでは公式テーマプラグイン @docusaurus/theme-mermaid を導入することで、Mermaid図解をネイティブに描画できます。

まずはプラグインをインストールします：

npm install @docusaurus/theme-mermaid

続いて、docusaurus.config.js にテーマ設定とmarkdown機能を追記します：

// docusaurus.config.js
module.exports = {
  // ...
  markdown: {
    mermaid: true, // Mermaidの解釈を有効化
  },
  themes: ['@docusaurus/theme-mermaid'], // テーマプラグインの登録
};

これで設定完了です！Markdownファイル内に ```mermaid でコードブロックを書くだけで、ブラウザ上にベクターSVG図面が自動生成されます。

```mermaid
graph LR
    User[開発者] -->|git push| GitHub[GitHub リポジトリ]
    GitHub -->|Actions 起動| CI[ビルドランナー]
    CI -->|HTML生成| Deploy[GitHub Pages]
    Deploy -->|配信| Reader[ドキュメント読者]
```

フローチャートやシーケンス図、ER図などのより詳しい構文実例は、当サイトの 【コピペで動く】Markdown Mermaid記法の書き方チートシート｜フローチャート・シーケンス図・ER図実例集 をあわせてご覧ください。

コードブロック・シンタックスハイライト・行強調機能

Docusaurusのコードブロックは、Prism.jsを内蔵しており、言語指定によるシンタックスハイライトはもちろん、タイトルバー表示や特定行の強調ハイライト（Highlighting lines）を標準でサポートしています。

```typescript title="src/utils/math.ts" {2,4-5}
export function add(a: number, b: number): number {
  // 2行目を強調ハイライト
  console.log(`Adding ${a} and ${b}`);
  // 4行目と5行目をハイライト
  return a + b;
}
```

コードブロック右上のワンクリックコピー機能も初期状態で標準装備されているため、読者にとって非常に快適なコード閲覧体験を提供できます。

サイトのデザイン・基本設定のカスタマイズ（docusaurus.config.js）

サイト全体のブランディングやナビゲーション構成は、プロジェクトルートにある docusaurus.config.js で集中的に管理します。

サイト名・ロゴ・ナビゲーションバー（ヘッダー/フッター）の編集

docusaurus.config.js の主要な設定ブロックは以下のようになっています。

// docusaurus.config.js
// @ts-check

/** @type {import('@docusaurus/types').Config} */
const config = {
  title: 'マークダウン開発マニュアル',
  tagline: 'MarkdownとDocusaurusで構築する最新技術ドキュメント',
  favicon: 'img/favicon.ico',

  // 公開先のURL設定（GitHub Pages用）
  url: 'https://username.github.io',
  baseUrl: '/my-website/',

  // GitHubリポジトリ情報
  organizationName: 'username',
  projectName: 'my-website',
  trailingSlash: false,

  themeConfig: {
    // ヘッダーナビゲーションバーの設定
    navbar: {
      title: 'Docs Portal',
      logo: {
        alt: 'サイトロゴ',
        src: 'img/logo.svg',
      },
      items: [
        {
          type: 'docSidebar',
          sidebarId: 'tutorialSidebar',
          position: 'left',
          label: 'ドキュメント',
        },
        { to: '/blog', label: 'ブログ', position: 'left' },
        {
          href: 'https://github.com/username/my-website',
          label: 'GitHub',
          position: 'right',
        },
      ],
    },
    // フッターメニューの設定
    footer: {
      style: 'dark',
      links: [
        {
          title: 'ドキュメント',
          items: [
            { label: 'クイックスタート', to: '/docs/intro' },
          ],
        },
        {
          title: 'コミュニティ',
          items: [
            { label: 'GitHub', href: 'https://github.com/username/my-website' },
          ],
        },
      ],
      copyright: `Copyright © ${new Date().getFullYear()} My Project, Inc. Built with Docusaurus.`,
    },
  },
};

module.exports = config;

ダークモード設定とカラーテーマの変更

Docusaurusは標準でダークモードとライトモードの切り替えトグルボタンをヘッダー右上に備えています。読者のOSテーマ設定（ダーク／ライト）も自動検出し、初期表示に反映します。

テーマカラー（メインカラー）を変更したい場合は、src/css/custom.css を編集します。Infima CSSのカスタムプロパティを書き換えることで、ブランドカラーに合わせた配色に瞬時に調整できます。

/* src/css/custom.css */
:root {
  /* ライトモード時のプライマリカラー */
  --ifm-color-primary: #2e8555;
  --ifm-color-primary-dark: #29784c;
  --ifm-color-primary-darker: #277148;
}

[data-theme='dark'] {
  /* ダークモード時のプライマリカラー */
  --ifm-color-primary: #25c2a0;
  --ifm-color-primary-dark: #21af90;
  --ifm-color-primary-darker: #1fa588;
}

サイト内ローカル検索機能（プラグイン導入）の有効化

マニュアルサイトにおいて読者が最も頻繁に利用するのが「サイト内全文検索」です。Docusaurusでは無料かつオフライン（サーバー不要）で動作する日本語対応のローカル検索プラグイン @easyops-cn/docusaurus-search-local が定番として使われています。

まずはパッケージをインストールします：

npm install @easyops-cn/docusaurus-search-local

docusaurus.config.js の themes 設定に日本語形態素解析オプション付きで追記します：

// docusaurus.config.js
module.exports = {
  // ...
  themes: [
    [
      require.resolve('@easyops-cn/docusaurus-search-local'),
      /** @type {import("@easyops-cn/docusaurus-search-local").PluginOptions} */
      ({
        hashed: true,
        language: ['en', 'ja'], // 日本語と英語のインデックスを有効化
        highlightSearchTermsOnTargetPage: true,
        explicitSearchResultPath: true,
      }),
    ],
  ],
};

これで、ヘッダーにスマートな検索バーが追加され、日本語の単語や見出しテキストを爆速でインクリメンタル検索できるようになります。

本番ビルドとGitHub Pagesへの無料デプロイ・公開手順

ドキュメントの執筆が完了したら、静的ファイル群として本番ビルドを行い、GitHub Pagesで世界中に無料公開しましょう。

本番用ビルド（npm run build）と確認

本番環境用の静的HTML/CSS/JavaScriptを生成するには、以下のビルドコマンドを実行します。

npm run build

ビルドが成功すると、プロジェクト直下に build/ ディレクトリが生成され、配下に完全な静的サイトアセットが出力されます。この静的ファイルをローカルで本番同様にプレビュー確認するには、npm run serve を実行します。

npm run serve

http://localhost:3000/ で本番ビルドされた成果物の動作やリンク切れがないかを事前にチェックできます。

GitHub Actionsを用いた自動デプロイ設定

チーム開発において最も推奨されるのが、GitHub Actionsを利用した完全自動デプロイです。リポジトリの main ブランチにMarkdownをプッシュするだけで、GitHubのCIランナーが自動でビルドし、GitHub Pagesへと反映してくれます。

リポジトリ直下に .github/workflows/deploy.yml を作成し、以下の設定を配置してください。

name: Deploy to GitHub Pages

on:
  push:
    branches:
      - main # mainブランチへのプッシュで自動実行

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: 'pages'
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: リポジトリのチェックアウト
        uses: actions/checkout@v4

      - name: Node.jsのセットアップ
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm

      - name: 依存パッケージのインストール
        run: npm ci

      - name: Docusaurusのビルド
        run: npm run build

      - name: Pagesアーティファクトのアップロード
        uses: actions/upload-pages-artifact@v3
        with:
          path: build

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: GitHub Pagesへのデプロイ
        id: deployment
        uses: actions/deploy-pages@v4

設定ファイルの作成後、GitHubリポジトリの画面で設定を有効化します：

1. GitHubリポジトリの 「Settings」＞「Pages」 を開きます。
2. 「Build and deployment」のSource項目で 「GitHub Actions」 を選択します。
3. コミット＆プッシュを実行するとワークフローが自動実行され、数分でサイトが世界中へ無料公開されます！

よくあるつまずき・エラーとトラブルシューティング

Docusaurusの導入やカスタマイズ時にエンジニアが遭遇しやすい典型的なエラーとその解決策をQ&A形式でまとめました。

まとめ：Markdown×Docusaurusで持続可能なドキュメント運用を始めよう

プレーンなMarkdownの書きやすさと、Reactエコシステムの圧倒的な柔軟性を兼ね備えた「Docusaurus」は、成長し続けるWebプロダクトやチームの仕様書運用を強力に支えてくれる最高峰のドキュメント生成ツールです。

シンプルなPython環境で素早く立ち上げたい場合はMkDocs、Reactコンポーネント連携や将来の多言語化・バージョン管理を見据えるならDocusaurusというように、プロジェクトの要件に応じて最適なツールを選び、Gitで管理できる高品質なドキュメント運用をぜひスタートさせてください！