Docusaurusでマニュアルを作る #2 サイドバーと検索 — ドキュメントの情報構造を組む

フレームワーク Docusaurus Documentation Static Site
読了 3分

#1でDocusaurusを使って最初のドキュメントを表示しました。記事が一つか二つのときは構造が問題になりません。問題はドキュメントが数十編に増えたときです。マニュアルでは、読者が「いま見ている項目が全体のどのあたりなのか」を常に把握できる必要があります。その役割を果たすのがサイドバーと検索です。

今回のシリーズはDocusaurusでマニュアルを作る全6回です。

  • #1 インストールから最初のドキュメントまで
  • #2 サイドバーと検索 — ドキュメントの情報構造を組む ← 今回の記事
  • #3 コンテンツ作成 — コードブロック、Mermaid、admonition
  • #4 Cloudflare Pagesでデプロイしてドメインを接続する
  • #5 多言語とバージョン管理
  • #6 メンテナンス — 検索、アクセシビリティ、ドキュメント文化

今回の記事はサイドバーを自動・手動で構成し、検索を付ける選択肢を整理します。

サイドバーはsidebars.jsで定義する #

Docusaurusのサイドバーはsidebars.jsで決まります。二つの方式があります。一つ目はフォルダ構造をそのままたどる自動生成です。基本テンプレートがこの方式です。

sidebars.js — 自動生成 
export default {
  docsSidebar: [{ type: 'autogenerated', dirName: '.' }],
};

自動生成では、各ドキュメントのsidebar_positionが順序を、フォルダの_category_.jsonがまとまりの名前を決めます。

docs/guide/_category_.json 
{ "label": "ガイド", "position": 2 }

直接定義する #

順序と構造を完全にコントロールしたい場合は、サイドバーを直接記述します。ドキュメントidを並べ、categoryでまとめます。

sidebars.js — 直接定義 
export default {
  docsSidebar: [
    'intro',
    {
      type: 'category',
      label: 'ガイド',
      items: ['guide/getting-started', 'guide/configuration'],
    },
  ],
};

上部メニュー(navbar)はdocusaurus.config.jsでサイドバーを指すようにします。

docusaurus.config.js — navbar 
navbar: {
  items: [
    { type: 'docSidebar', sidebarId: 'docsSidebar', label: 'ドキュメント' },
  ],
}

検索 — 内蔵ではない #

ここでDocusaurusは先のツールたちと違います。Hugo HextraやMkDocs Materialが検索を標準で内蔵していたのとは違い、Docusaurusは検索を自分で付ける必要があります。選択肢は二つです。

  • Algolia DocSearch — Docusaurusが公式にサポートするホスティング検索です。オープンソースプロジェクトであれば無料で申請でき、インデックスをAlgoliaが管理します。
  • ローカル検索プラグイン — @easyops-cn/docusaurus-search-localのようなプラグインを使えば、ビルド時点でインデックスを作って外部サービスなしで動作します。日本語を含む社内ドキュメントであれば、こちらが便利です。

付ける具体的な方法は、運用を扱う#6で整理します。

まとめ #

今回の記事では、sidebars.jsでサイドバーを自動・手動で構成し、上部メニューを接続し、検索の二つの選択肢を見てきました。検索が一段階だけ手間がかかるという点を除けば、情報構造を組む流れは他のツールと同じです。

次回はコンテンツ作成を扱います。コードブロックとMermaidのダイアグラム、そして注意・警告を強調するadmonitionまで、ドキュメントを読みやすくする要素を整理します。

X