Docusaurusカスタマイズ方法あれこれ

Docusaurusとは

Docusaurusは、Facebookが開発したオープンソースの静的サイトジェネレーターです。ReactベースのDocusaurusは、ドキュメントサイトの構築に特化しており、開発者にとって使いやすく、機能的なドキュメンテーションを簡単に作成できるように設計されています。

Docusaurusの概要と特徴

Docusaurusは、以下のような特徴を持っています：

Reactベース: DocusaurusはReactを使用しているため、Reactの知識があれば、カスタマイズや拡張が容易です。
Markdownサポート: ドキュメントはMarkdownで書くことができ、Docusaurusが自動的にHTMLに変換します。
バージョン管理: ドキュメントのバージョン管理が簡単で、古いバージョンのドキュメントも保持できます。
検索機能: 組み込みの検索機能により、ユーザーはドキュメント内を簡単に検索できます。
レスポンシブデザイン: Docusaurusは、デスクトップ、タブレット、モバイルなど、様々なデバイスに対応しています。

Reactベースの静的サイトジェネレーター

Docusaurusは、Reactを使用した静的サイトジェネレーターです。これにより、開発者はReactのコンポーネントを使ってサイトをカスタマイズでき、必要に応じてインタラクティブな要素を追加することができます。また、Reactの仮想DOMにより、高いパフォーマンスを実現しています。

ドキュメントサイトの構築に最適化

Docusaurusは、ドキュメントサイトの構築に特化しています。ドキュメントのバージョン管理、検索機能、サイドバーナビゲーションなど、ドキュメントサイトに必要な機能が標準で備わっています。これにより、開発者はドキュメントの内容に集中でき、サイトの構築に時間をかける必要がありません。

以上のように、Docusaurusは、Reactベースの静的サイトジェネレーターであり、ドキュメントサイトの構築に最適化されています。次の章では、Docusaurusのインストールと初期設定について説明します。

Docusaurusのインストールと初期設定

Docusaurusを使い始めるには、まずNode.jsとnpmのインストールが必要です。その後、Docusaurusの新規プロジェクトを作成し、開発サーバーを起動して確認します。

Node.jsとnpmのインストール

Node.js公式サイトにアクセスします。
LTS（Long Term Support）バージョンをダウンロードしてインストールします。
ターミナルまたはコマンドプロンプトを開き、以下のコマンドを実行してインストールを確認します：
```
node -v
npm -v
```
これにより、Node.jsとnpmのバージョンが表示されます。

Docusaurusの新規プロジェクト作成

プロジェクトを作成するディレクトリに移動します。
以下のコマンドを実行して、Docusaurusの新規プロジェクトを作成します：
- npm
- Yarn
- pnpm
npx create-docusaurus@latest my-website classic
npx create-docusaurus@latest my-website classic
npx create-docusaurus@latest my-website classic
my-websiteは、プロジェクトの名前です。必要に応じて変更してください。
以下のコマンドを実行して、プロジェクトのディレクトリに移動します：
```
cd my-website
```

開発サーバーの起動と確認

以下のコマンドを実行して、開発サーバーを起動します：
- npm
- Yarn
- pnpm
npm start
yarn start
pnpm start
ブラウザでhttp://localhost:3000にアクセスします。
Docusaurusのデフォルトのホームページが表示されれば、インストールと初期設定は完了です。

以下は、実行結果の例です：

[INFO] Starting the development server...
[SUCCESS] Docusaurus website is running at: http://localhost:3000/

これで、Docusaurusのインストールと初期設定が完了しました。次の章では、サイドバーのカスタマイズについて説明します。

サイドバーのカスタマイズ

Docusaurusのサイドバーは、ドキュメントの構造を表示し、ユーザーがコンテンツを探しやすくするために重要な役割を果たします。ここでは、サイドバーの構造と設定ファイル、ドキュメントの階層構造の変更、カテゴリの追加と並び替えについて説明します。

サイドバーの構造と設定ファイル

Docusaurusのサイドバーは、sidebars.jsファイルで設定します。このファイルは、プロジェクトのルートディレクトリに位置しています。サイドバーの構造は、以下のようなオブジェクトで定義します：

module.exports = {
  docs: [
    {
      type: 'category',
      label: 'Getting Started',
      items: ['doc1', 'doc2', 'doc3'],
    },
    // ... その他のカテゴリやドキュメント
  ],
};

docs：サイドバーの構造を定義するオブジェクト
type：'category'または'doc'を指定
label：カテゴリの名前
items：カテゴリに属するドキュメントのID（ファイル名から拡張子を除いたもの）の配列

ドキュメントの階層構造の変更

ドキュメントの階層構造を変更するには、sidebars.jsファイルを編集します。たとえば、以下のようにitems配列の順序を変更することで、ドキュメントの表示順を変更できます：

module.exports = {
  docs: [
    {
      type: 'category',
      label: 'Getting Started',
      items: ['doc2', 'doc1', 'doc3'], // 順序を変更
    },
    // ... その他のカテゴリやドキュメント
  ],
};

カテゴリの追加と並び替え

新しいカテゴリを追加するには、sidebars.jsファイルに新しいカテゴリオブジェクトを追加します：

module.exports = {
  docs: [
    {
      type: 'category',
      label: 'Getting Started',
      items: ['doc1', 'doc2', 'doc3'],
    },
    {
      type: 'category',
      label: 'Advanced Topics', // 新しいカテゴリを追加
      items: ['doc4', 'doc5'],
    },
  ],
};

カテゴリの並び替えは、カテゴリオブジェクトの順序を変更することで実現できます。

以上のように、Docusaurusのサイドバーはsidebars.jsファイルで設定し、ドキュメントの階層構造の変更やカテゴリの追加・並び替えが可能です。次の章では、ナビゲーションバーのカスタマイズについて説明します。

ナビゲーションバーのカスタマイズ

Docusaurusのナビゲーションバーは、サイトの主要なセクションへのリンクを提供し、ユーザーがサイト内を移動しやすくします。ここでは、ナビゲーションバーの設定ファイル、リンクの追加と並び替え、ドロップダウンメニューの作成について説明します。

ナビゲーションバーの設定ファイル

ナビゲーションバーは、docusaurus.config.jsファイルのthemeConfigオブジェクト内のnavbarプロパティで設定します。以下は、基本的な構造の例です：

module.exports = {
  // ...
  themeConfig: {
    navbar: {
      title: 'My Website',
      logo: {
        alt: 'My Website Logo',
        src: 'img/logo.svg',
      },
      items: [
        {
          to: 'docs/doc1',
          activeBasePath: 'docs',
          label: 'Docs',
          position: 'left',
        },
        // ... その他のリンク
      ],
    },
    // ...
  },
};

title：ナビゲーションバーに表示されるサイトのタイトル
logo：サイトのロゴ画像の設定
items：ナビゲーションバーに表示するリンクの配列

リンクの追加と並び替え

新しいリンクを追加するには、items配列に新しいオブジェクトを追加します：

module.exports = {
  // ...
  themeConfig: {
    navbar: {
      // ...
      items: [
        // ...
        {
          to: 'blog',
          label: 'Blog',
          position: 'left',
        },
      ],
    },
    // ...
  },
};

リンクの並び替えは、items配列内のオブジェクトの順序を変更することで実現できます。

ドロップダウンメニューの作成

ドロップダウンメニューを作成するには、items配列内にtype: 'dropdown'のオブジェクトを追加します：

module.exports = {
  // ...
  themeConfig: {
    navbar: {
      // ...
      items: [
        // ...
        {
          type: 'dropdown',
          label: 'Community',
          position: 'right',
          items: [
            {
              label: 'Twitter',
              href: 'https://twitter.com/docusaurus',
            },
            {
              label: 'Discord',
              href: 'https://discordapp.com/invite/docusaurus',
            },
          ],
        },
      ],
    },
    // ...
  },
};

type: 'dropdown'：ドロップダウンメニューであることを指定
label：ドロップダウンメニューのラベル
items：ドロップダウンメニュー内のリンクの配列

以上のように、Docusaurusのナビゲーションバーはdocusaurus.config.jsファイルで設定し、リンクの追加・並び替えやドロップダウンメニューの作成が可能です。

カラーモードの切り替えを無効にする

デフォルトではカラーモードの切り替えが有効になっています。ヘッダー右にある太陽アイコンで切り替えができます。私は必要なかったので、無効にする設定をしました。

docusaurus.config.js
module.exports = {
  themeConfig:
    ({
      colorMode: {
        defaultMode: 'light',
        disableSwitch: true,
      },
  },
};

フッターのカスタマイズ

Docusaurusのフッターは、サイトの追加情報やリンクを提供する重要な要素です。ここでは、フッターの設定ファイル、リンクの追加と並び替え、スタイルのカスタマイズについて説明します。

フッターの設定ファイル

フッターは、docusaurus.config.jsファイルのthemeConfigオブジェクト内のfooterプロパティで設定します。以下は、基本的な構造の例です：

module.exports = {
  // ...
  themeConfig: {
    footer: {
      style: 'dark',
      links: [
        {
          title: 'Docs',
          items: [
            {
              label: 'Getting Started',
              to: 'docs/doc1',
            },
          ],
        },
        // ... その他のリンク
      ],
      copyright: `Copyright © ${new Date().getFullYear()} My Website, Inc. Built with Docusaurus.`,
    },
    // ...
  },
};

style：フッターのスタイル（'dark'または'light'）
links：フッターに表示するリンクのカテゴリの配列
copyright：フッターに表示する著作権情報

リンクの追加と並び替え

新しいリンクを追加するには、links配列内の適切なカテゴリに新しいオブジェクトを追加します：

module.exports = {
  // ...
  themeConfig: {
    footer: {
      // ...
      links: [
        {
          title: 'Community',
          items: [
            {
              label: 'Twitter',
              href: 'https://twitter.com/docusaurus',
            },
            {
              label: 'Discord',
              href: 'https://discordapp.com/invite/docusaurus',
            },
          ],
        },
      ],
      // ...
    },
    // ...
  },
};

リンクの並び替えは、items配列内のオブジェクトの順序を変更することで実現できます。

スタイルのカスタマイズ

フッターのスタイルをカスタマイズするには、src/css/custom.cssファイルにCSSを追加します。例えば、フッターのテキストの色を変更するには、以下のようなCSSを追加します：

.footer {
  color: #ffffff;
}

また、docusaurus.config.jsファイルのthemeConfig.footer.styleプロパティを変更することで、フッターの背景色を'dark'または'light'に設定できます。

以上のように、Docusaurusのフッターはdocusaurus.config.jsファイルで設定し、リンクの追加・並び替えやスタイルのカスタマイズが可能です。次の章では、検索機能の設定について説明します。

6. 検索機能の設定

Docusaurusには、強力な検索機能が組み込まれており、ユーザーがサイト内のコンテンツを素早く見つけられるようにします。ここでは、検索機能の有効化、検索対象の設定、検索結果のスタイルのカスタマイズについて説明します。

検索機能の有効化

デフォルトでは、Docusaurusの検索機能は無効になっています。検索機能を有効にするには、docusaurus.config.jsファイルのthemeConfigオブジェクト内にalgoliaプロパティを追加します：

module.exports = {
  // ...
  themeConfig: {
    // ...
    algolia: {
      apiKey: 'YOUR_API_KEY',
      indexName: 'YOUR_INDEX_NAME',
      contextualSearch: true,
      appId: 'YOUR_APP_ID',
    },
    // ...
  },
};

apiKey：AlgoliaのAPIキー
indexName：Algoliaのインデックス名
contextualSearch：コンテキスト検索の有効化（trueまたはfalse）
appId：AlgoliaのアプリケーションID

検索対象の設定

デフォルトでは、Docusaurusはdocsディレクトリ内のすべてのMarkdownファイルを検索対象としています。検索対象を変更するには、docusaurus.config.jsファイルのpresetsセクションを編集します：

module.exports = {
  // ...
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          // ...
          sidebarPath: require.resolve('./sidebars.js'),
          // 検索対象のパスを設定
          include: ['docs/**/*.md', 'docs/**/*.mdx'],
          // 検索対象から除外するパスを設定
          exclude: ['docs/api/**'],
        },
        // ...
      },
    ],
  ],
  // ...
};

include：検索対象に含めるパスの配列
exclude：検索対象から除外するパスの配列

検索結果のスタイルのカスタマイズ

検索結果のスタイルをカスタマイズするには、src/css/custom.cssファイルにCSSを追加します。例えば、検索結果のタイトルの色を変更するには、以下のようなCSSを追加します：

.algolia-docsearch-suggestion--title {
  color: #1877f2;
}

また、Algoliaのダッシュボードから検索結果のスタイルを設定することもできます。

以上のように、Docusaurusの検索機能はdocusaurus.config.jsファイルで設定し、検索対象の設定や検索結果のスタイルのカスタマイズが可能です。次の章では、カスタムCSSの適用について説明します。

7. カスタムCSSの適用

Docusaurusでは、デフォルトのスタイルに加えて、カスタムCSSを適用することでサイトの見た目をカスタマイズできます。ここでは、カスタムCSSファイルの作成、CSSの読み込み、サイト全体のスタイル変更について説明します。

カスタムCSSファイルの作成

カスタムCSSを適用するには、まずsrc/css/custom.cssファイルを作成します。このファイルがない場合は、新しく作成してください。

touch src/css/custom.css

CSSの読み込み

src/css/custom.cssファイルを作成したら、Docusaurusが自動的にこのファイルを読み込みます。追加の設定は必要ありません。

サイト全体のスタイル変更

src/css/custom.cssファイルに記述したCSSは、サイト全体に適用されます。例えば、以下のようなCSSを追加することで、サイトのフォントファミリーを変更できます：

body {
  font-family: Arial, sans-serif;
}

また、特定の要素のスタイルを変更するには、適切なセレクターを使用します。例えば、ヘッダーの背景色を変更するには、以下のようなCSSを追加します：

.navbar {
  background-color: #1877f2;
}

Docusaurusでは、CSSモジュールもサポートされています。CSSモジュールを使用すると、コンポーネントごとにスタイルを定義でき、スタイルの衝突を防ぐことができます。CSSモジュールを使用するには、.module.css拡張子を持つCSSファイルを作成し、そのファイルをReactコンポーネントでインポートします。

例えば、src/components/Header.module.cssファイルを作成し、以下のようなCSSを追加します：

.header {
  background-color: #1877f2;
  padding: 1rem;
}

次に、src/components/Header.jsファイルで以下のようにCSSモジュールをインポートします：

import React from 'react';
import styles from './Header.module.css';

export default function Header() {
  return <header className={styles.header}>...</header>;
}

以上のように、DocusaurusではカスタムCSSを適用することでサイトの見た目をカスタマイズできます。次の章では、カスタムJavaScriptの適用について説明します。

Docusaurusカスタマイズ方法あれこれ

Docusaurusとは​

Docusaurusの概要と特徴​

Reactベースの静的サイトジェネレーター​

ドキュメントサイトの構築に最適化​

Docusaurusのインストールと初期設定​

Node.jsとnpmのインストール​

Docusaurusの新規プロジェクト作成​

開発サーバーの起動と確認​

サイドバーのカスタマイズ​

サイドバーの構造と設定ファイル​

ドキュメントの階層構造の変更​

カテゴリの追加と並び替え​

ナビゲーションバーのカスタマイズ​

ナビゲーションバーの設定ファイル​

リンクの追加と並び替え​

ドロップダウンメニューの作成​

カラーモードの切り替えを無効にする​

フッターのカスタマイズ​

フッターの設定ファイル​

リンクの追加と並び替え​

スタイルのカスタマイズ​

6. 検索機能の設定​

検索機能の有効化​

検索対象の設定​

検索結果のスタイルのカスタマイズ​

7. カスタムCSSの適用​

カスタムCSSファイルの作成​

CSSの読み込み​

サイト全体のスタイル変更​

Docusaurusとは

Docusaurusの概要と特徴

Reactベースの静的サイトジェネレーター

ドキュメントサイトの構築に最適化

Docusaurusのインストールと初期設定

Node.jsとnpmのインストール

Docusaurusの新規プロジェクト作成

開発サーバーの起動と確認

サイドバーのカスタマイズ

サイドバーの構造と設定ファイル

ドキュメントの階層構造の変更

カテゴリの追加と並び替え

ナビゲーションバーのカスタマイズ

ナビゲーションバーの設定ファイル

リンクの追加と並び替え

ドロップダウンメニューの作成

カラーモードの切り替えを無効にする

フッターのカスタマイズ

フッターの設定ファイル

リンクの追加と並び替え

スタイルのカスタマイズ

6. 検索機能の設定

検索機能の有効化

検索対象の設定

検索結果のスタイルのカスタマイズ

7. カスタムCSSの適用

カスタムCSSファイルの作成

CSSの読み込み

サイト全体のスタイル変更