ドキュメント作成ツール

Docusaurus

概要

DocusaurusはFacebook（Meta）が開発したReactベースの静的サイトジェネレータです。OSS文書化に特化し、MDX対応、バージョニング、国際化機能を統合した現代的なドキュメントサイト構築プラットフォームです。

詳細

Docusaurus（ドキュサウルス）は2017年にFacebook（現Meta）によって開発され、オープンソースプロジェクトのドキュメント作成に革新をもたらしました。React基盤により、マークダウンファイルから美しく機能的なWebサイトを生成できます。MDX（Markdown + JSX）サポートにより、Reactコンポーネントを直接ドキュメントに埋め込むことが可能です。プラグインシステムにより、機能拡張と柔軟なカスタマイズを実現できます。バージョニング機能により、複数バージョンのドキュメントを並行管理できます。国際化（i18n）機能により、多言語対応サイトを効率的に構築できます。検索機能、SEO最適化、高速な静的サイト生成により、優れたユーザー体験を提供します。テーマシステムにより、デザインとレイアウトの完全なカスタマイズが可能です。2025年現在、React、Vue.js、Node.js、Babel、Jest等の著名なOSSプロジェクトで採用され、技術コミュニティの標準的なドキュメントプラットフォームとして確立されています。デベロッパーフレンドリーな設計により、Git-basedワークフローとCI/CD統合も容易に実現できます。

メリット・デメリット

メリット

• React基盤の柔軟性: MDXによるReactコンポーネント統合で高度なインタラクティブコンテンツ
• OSS特化設計: バージョニング、リリースノート、APIドキュメント生成の標準機能
• 多言語対応: 国際化機能による効率的な多言語サイト構築
• 高速パフォーマンス: 静的サイト生成による高速ロードと優れたSEO
• 豊富なプラグイン: アルゴリア検索、Mermaid図表、Google Analytics等の統合
• Git統合: マークダウンファイルによるバージョン管理とコラボレーション
• カスタマイズ性: React知識により無限のデザインとレイアウト調整

デメリット

• 学習コスト: React/JSXの知識が必要、初期セットアップの複雑さ
• Node.js依存: 開発環境とビルドプロセスのNode.js必須依存
• OSS特化: 企業内文書やWiki用途には機能過多
• ビルド時間: 大規模サイトでのビルド時間増加
• 複雑性: 小規模プロジェクトには機能が豊富すぎる場合
• React学習曲線: 高度なカスタマイズにはReact開発スキルが必要

主要リンク

• Docusaurus公式サイト
• Docusaurusドキュメント
• GitHub リポジトリ
• プラグインマーケットプレイス
• コミュニティ
• ショーケース

書き方の例

基本的なプロジェクト構成

# Docusaurusプロジェクトの作成
npx create-docusaurus@latest my-website classic

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

docusaurus.config.js設定

// @ts-check
import { themes as prismThemes } from 'prism-react-renderer';

/** @type {import('@docusaurus/types').Config} */
const config = {
  title: 'プロジェクト名',
  tagline: 'プロジェクトの説明',
  favicon: 'img/favicon.ico',

  // サイトURLとベースURL
  url: 'https://your-docusaurus-site.example.com',
  baseUrl: '/',

  // GitHub pages デプロイ設定
  organizationName: 'your-github-org',
  projectName: 'your-repo-name',

  onBrokenLinks: 'throw',
  onBrokenMarkdownLinks: 'warn',

  // 国際化設定
  i18n: {
    defaultLocale: 'ja',
    locales: ['ja', 'en'],
  },

  presets: [
    [
      'classic',
      /** @type {import('@docusaurus/preset-classic').Options} */
      ({
        docs: {
          sidebarPath: require.resolve('./sidebars.js'),
          editUrl: 'https://github.com/your-org/your-repo/tree/main/',
          versions: {
            current: {
              label: 'v3.x (開発版)',
              path: 'next',
            },
          },
          lastVersion: 'current',
          showLastUpdateAuthor: true,
          showLastUpdateTime: true,
        },
        blog: {
          showReadingTime: true,
          editUrl: 'https://github.com/your-org/your-repo/tree/main/',
        },
        theme: {
          customCss: require.resolve('./src/css/custom.css'),
        },
        gtag: {
          trackingID: 'G-XXXXXXXXXX',
          anonymizeIP: true,
        },
      }),
    ],
  ],

  themeConfig:
    /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
    ({
      image: 'img/docusaurus-social-card.jpg',
      navbar: {
        title: 'プロジェクト名',
        logo: {
          alt: 'ロゴ',
          src: 'img/logo.svg',
        },
        items: [
          {
            type: 'docSidebar',
            sidebarId: 'tutorialSidebar',
            position: 'left',
            label: 'ドキュメント',
          },
          { to: '/blog', label: 'ブログ', position: 'left' },
          {
            type: 'docsVersionDropdown',
            position: 'right',
          },
          {
            type: 'localeDropdown',
            position: 'right',
          },
          {
            href: 'https://github.com/your-org/your-repo',
            label: 'GitHub',
            position: 'right',
          },
        ],
      },
      footer: {
        style: 'dark',
        links: [
          {
            title: 'ドキュメント',
            items: [
              {
                label: 'チュートリアル',
                to: '/docs/intro',
              },
            ],
          },
          {
            title: 'コミュニティ',
            items: [
              {
                label: 'Discord',
                href: 'https://discordapp.com/invite/docusaurus',
              },
              {
                label: 'Twitter',
                href: 'https://twitter.com/docusaurus',
              },
            ],
          },
        ],
        copyright: "Copyright © " + new Date().getFullYear() + " My Project, Inc. Built with Docusaurus.",
      },
      prism: {
        theme: prismThemes.github,
        darkTheme: prismThemes.dracula,
        additionalLanguages: ['java', 'php', 'rust', 'elixir'],
      },
      algolia: {
        appId: 'YOUR_APP_ID',
        apiKey: 'YOUR_SEARCH_API_KEY',
        indexName: 'YOUR_INDEX_NAME',
        contextualSearch: true,
      },
    }),

  plugins: [
    '@docusaurus/theme-mermaid',
    [
      '@docusaurus/plugin-content-docs',
      {
        id: 'api',
        path: 'api',
        routeBasePath: 'api',
        sidebarPath: require.resolve('./sidebarsApi.js'),
      },
    ],
  ],

  themes: ['@docusaurus/theme-mermaid'],

  markdown: {
    mermaid: true,
  },
};

export default config;

MDXファイルの作成

---
id: getting-started
title: はじめに
sidebar_label: クイックスタート
sidebar_position: 1
description: プロジェクトの導入ガイド
keywords: [setup, installation, quickstart]
---

# プロジェクトのはじめに

プロジェクトへようこそ！このガイドでは、セットアップから基本的な使用方法まで説明します。

## インストール

```bash
npm install your-package

基本的な使用方法

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

graph TD
    A[ユーザー] --> B[API ゲートウェイ]
    B --> C[認証サービス]
    B --> D[ビジネスロジック]
    D --> E[データベース]
    D --> F[外部サービス]

### カスタムReactコンポーネントの作成
```jsx
// src/components/FeatureList.js
import React from 'react';
import clsx from 'clsx';
import styles from './styles.module.css';

const FeatureList = [
  {
    title: '簡単に使える',
    Svg: require('@site/static/img/undraw_docusaurus_mountain.svg').default,
    description: (
      <>
        Docusaurusは簡単にセットアップできるように設計されています。
        <code>docs</code>にマークダウンファイルを追加するだけで動作します。
      </>
    ),
  },
  {
    title: '重要なことに集中',
    Svg: require('@site/static/img/undraw_docusaurus_tree.svg').default,
    description: (
      <>
        Docusaurusはドキュメント作成に集中できるように設計されています。
        <code>docs</code>ディレクトリにファイルを移動するだけです。
      </>
    ),
  },
  {
    title: 'React で拡張',
    Svg: require('@site/static/img/undraw_docusaurus_react.svg').default,
    description: (
      <>
        DocusaurusはReactを再利用することで拡張できます。
        レイアウトをカスタマイズしながらも、同じヘッダーとフッターを再利用できます。
      </>
    ),
  },
];

function Feature({Svg, title, description}) {
  return (
    <div className={clsx('col col--4')}>
      <div className="text--center">
        <Svg className={styles.featureSvg} role="img" />
      </div>
      <div className="text--center padding-horiz--md">
        <h3>{title}</h3>
        <p>{description}</p>
      </div>
    </div>
  );
}

export default function HomepageFeatures() {
  return (
    <section className={styles.features}>
      <div className="container">
        <div className="row">
          {FeatureList.map((props, idx) => (
            <Feature key={idx} {...props} />
          ))}
        </div>
      </div>
    </section>
  );
}

// plugins/custom-plugin.js
module.exports = function (context, options) {
  return {
    name: 'custom-plugin',
    configureWebpack(config, isServer, utils) {
      return {
        resolve: {
          alias: {
            '@components': path.resolve(__dirname, '../src/components'),
          },
        },
      };
    },
    getThemePath() {
      return path.resolve(__dirname, './theme');
    },
    contentLoaded({content, actions}) {
      const {addRoute, createData} = actions;
      // カスタムルートの追加
      addRoute({
        path: '/custom-page',
        component: '@theme/CustomPage',
        exact: true,
      });
    },
  };
};

// i18n/ja/docusaurus-plugin-content-docs/current.json
{
  "version.label": {
    "message": "次",
    "description": "The label for version current"
  },
  "sidebar.tutorialSidebar.category.Tutorial - Basics": {
    "message": "チュートリアル - 基本",
    "description": "The label for category Tutorial - Basics in sidebar tutorialSidebar"
  }
}

// i18n/ja/code.json
{
  "theme.common.edit": {
    "message": "このページを編集",
    "description": "The edit button label on doc pages"
  },
  "theme.common.next": {
    "message": "次へ",
    "description": "The next button label on doc pages"
  }
}

# .github/workflows/deploy.yml
name: Deploy to GitHub Pages

on:
  push:
    branches:
      - main

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

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

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 18
          cache: npm

      - name: Install dependencies
        run: npm ci
      - name: Build website
        run: npm run build

      - name: Setup Pages
        uses: actions/configure-pages@v4
      - name: Upload artifact
        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: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

# 新しいバージョンの作成
npm run docusaurus docs:version 1.0

# バージョン構造
website/
├── versioned_docs/
│   ├── version-1.0/
│   └── version-2.0/
├── versioned_sidebars/
│   ├── version-1.0-sidebars.json
│   └── version-2.0-sidebars.json
└── versions.json

// Algolia DocSearch設定
module.exports = {
  themeConfig: {
    algolia: {
      appId: 'YOUR_APP_ID',
      apiKey: 'YOUR_SEARCH_API_KEY',
      indexName: 'YOUR_INDEX_NAME',
      contextualSearch: true,
      searchParameters: {},
      searchPagePath: 'search',
    },
  },
};