Zenn
🦖

Docusaurusの使い方

2024/07/01に公開
Markdown
Docusaurus
Mermaid
Mermaid JS
tech

はじめに

マークダウンファイルを静的サイトとして生成できたり、mermaidjs、redoc、Swagger, openapi.jsonなどのサイトも取り込める便利なツールを見つけたので記述する
Docusaurusは静的サイトジェネレーターで、主に技術文書やドキュメントサイトの構築に使用されます。このガイドでは、TypeScriptを使用してDocusaurusをインストールし、設定ファイル(docusaurus.config.tsとsidebars.ts)の書き方を解説します。
https://docusaurus.io/

目次

  1. フォルダ構成
  2. Docusaurusのインストール
  3. 初期設定
  4. docusaurus.config.tsの書き方
  5. sidebars.tsの書き方
  6. OpenAPIドキュメントの生成
  7. まとめ

完成形イメージ

1. フォルダ構成

Docusaurusプロジェクトの基本的なフォルダ構成は以下のようになります。

my-website/
├── blog/
├── docs/
│   ├── getting-started/
│   ├── architecture-design/
│   └── api/
├── src/
│   └── css/
│       └── custom.css
├── static/
│   └── img/
│       └── favicon.ico
├── docusaurus.config.ts
└── sidebars.ts
  • blog/: ブログ記事を格納するディレクトリ
  • docs/: ドキュメントを格納するディレクトリ
  • src/: カスタムCSSやコンポーネントを格納するディレクトリ
  • static/: 静的ファイル（画像など）を格納するディレクトリ
  • docusaurus.config.ts: Docusaurusのメイン設定ファイル
  • sidebars.ts: サイドバーの設定ファイル

2. Docusaurusのインストール

Docusaurusをプロジェクトにインストールするためには、Node.jsとnpmが必要です。以下のコマンドを実行してインストールします。

npx create-docusaurus@latest my-website classic --typescript
cd my-website
npm install

3. 初期設定

プロジェクトを初期化した後、my-websiteディレクトリに移動します。ここで、主要な設定ファイルであるdocusaurus.config.tsとsidebars.tsを編集していきます。

4. docusaurus.config.tsの書き方

設定項目の概要

以下の表は、docusaurus.config.tsで使用される主要な設定項目とその説明です。

設定項目 説明
title サイトのタイトル
tagline サイトのキャッチフレーズ
favicon サイトのファビコンのパス
url サイトのURL
baseUrl サイトのベースURL
onBrokenLinks 壊れたリンクが見つかったときの動作
onBrokenMarkdownLinks 壊れたMarkdownリンクが見つかったときの動作
i18n 多言語対応の設定
presets 使用するプリセットとその設定
themeConfig テーマの設定

docusaurus.config.tsの例

以下に、具体的なdocusaurus.config.tsの例を示します。この例では、Docusaurusの基本設定とRedocの埋め込みを行っています。

import { themes as prismThemes } from 'prism-react-renderer';
import type { Config } from '@docusaurus/types';
import type * as Preset from '@docusaurus/preset-classic';

const config: Config = {
  title: 'My Site',
  tagline: 'Dinosaurs are cool',
  favicon: 'img/favicon.ico',

  url: 'https://your-docusaurus-site.example.com',
  baseUrl: '/',

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

  i18n: {
    defaultLocale: 'en',
    locales: ['en'],
  },

  presets: [
    [
      'classic',
      {
        docs: {
          sidebarPath: require.resolve('./sidebars.ts'),
        },
        blog: {
          showReadingTime: true,
        },
        theme: {
          customCss: require.resolve('./src/css/custom.css'),
        },
      } satisfies Preset.Options,
    ],
    ['redocusaurus',
      {
        specs: [
          {
            id: 'sample_file',
            spec: './openapi.json',
            route: '/api-docs',
          },
        ],
        theme: {
          primaryColor: '#1890ff',
        },
      },
    ],
  ],

  themeConfig: {
    image: 'img/docusaurus-social-card.jpg',
    navbar: {
      title: 'My Site',
      logo: {
        alt: 'My Site Logo',
        src: 'img/logo.svg',
      },
      items: [
        {
          type: 'docSidebar',
          sidebarId: 'gettingStartedSidebar',
          position: 'left',
          label: 'Getting Started',
        },
        {
          type: 'docSidebar',
          sidebarId: 'architectureDesignSidebar',
          position: 'left',
          label: 'Architecture Design',
        },
        {
          to: '/api-docs',
          label: 'API Docs',
          position: 'left',
        },
      ],
    },
    footer: {
      style: 'dark',
      links: [
        {
          title: 'Docs',
          items: [
            {
              label: 'Getting Started',
              to: '/docs/getting-started/intro',
            },
            {
              label: 'Architecture Design',
              to: '/docs/architecture-design/intro',
            },
          ],
        },
      ],
      copyright: `Copyright © ${new Date().getFullYear()} My Project, Inc. Built with Docusaurus.`,
    },
    prism: {
      theme: prismThemes.github,
      darkTheme: prismThemes.dracula,
    },
  } satisfies Preset.ThemeConfig,
};

export default config;

5. sidebars.tsの書き方

設定項目の概要

以下の表は、sidebars.tsで使用される主要な設定項目とその説明です。

設定項目 説明
gettingStartedSidebar 自動生成されたサイドバーの設定
architectureDesignSidebar 自動生成されたサイドバーの設定
apiSidebar 自動生成されたサイドバーの設定

sidebars.tsの例

以下に、具体的なsidebars.tsの例を示します。この例では、自動生成されたサイドバーを設定しています。

import type { SidebarsConfig } from '@docusaurus/plugin-content-docs';

const sidebars: SidebarsConfig = {
  gettingStartedSidebar: [{ type: 'autogenerated', dirName: 'getting-started' }],
  architectureDesignSidebar: [{ type: 'autogenerated', dirName: 'architecture-design' }],
  apiSidebar: [{ type: 'autogenerated', dirName: 'api' }],
};

export default sidebars;

6. OpenAPIドキュメントの生成

Docusaurusは、Redocusaurusプラグインを使用してOpenAPI仕様からAPIドキュメントを生成することができます。以下に、設定方法を示します。

docusaurus.config.tsでの設定

Redocusaurusプラグインを使用するために、docusaurus.config.tsに以下の設定を追加します。

presets: [
  [
    'classic',
    {
      docs: {
        sidebarPath: require.resolve('./sidebars.ts'),
      },
      blog: {
        showReadingTime: true,
      },
      theme: {
        customCss: require.resolve('./src/css/custom.css'),
      },
    } satisfies Preset.Options,
  ],
  ['redocusaurus',
    {
      specs: [
        {
          id: 'sample_file',
          spec: './openapi.json',
          route: '/api-docs',
        },
      ],
      theme: {
        primaryColor: '#1890ff',
      },
    },
  ],
],

この設定により、openapi.jsonファイルを使用して/api-docsルートにAPIドキュメントを生成します。

openapi.jsonの配置

openapi.jsonファイルをプロジェクトのルートディレクトリに配置します。このファイルには、OpenAPI仕様に従ったAPI定義が含まれています。

7. まとめ

このガイドでは、Docusaurusのインストールから初期設定、主要な設定ファイルの書き方、そしてOpenAPIドキュメントの生成までを解説しました。Docusaurusを使用することで、効率的にドキュメントサイトを構築することができます。設定ファイルの書き方に慣れることで、カスタマイズも簡単に行えるようになります。

Discussion