MkDocsでマニュアルを作る #2 navと検索 — ドキュメントの情報構造を整える
#1でMkDocs Materialで最初のドキュメントを表示しました。記事が1〜2編のうちは構造は問題になりません。問題はドキュメントが数十編に増えたときです。マニュアルは、読者が「いま見ている項目が全体のどのあたりなのか」を常に把握できなければなりません。その役割を果たすのがサイドバーと検索です。MkDocsではサイドバーをnavと呼びます。
今回のシリーズはMkDocsでマニュアルを作る全6回です。
- #1 インストールから最初のドキュメントまで
- #2 navと検索 — ドキュメントの情報構造を整える ← この記事
- #3 コンテンツ作成 — コードブロック、Mermaid、admonition
- #4 Cloudflare Pagesでデプロイしてドメインをつなぐ
- #5 多言語とバージョン管理
- #6 メンテナンス — 検索、アクセシビリティ、ドキュメント文化
この記事では、navを直接設計し、Materialのナビゲーション機能をオンにし、検索を整えるところまで扱います。
navはmkdocs.ymlに直接書く #
ここでMkDocsの性格がはっきり表れます。サイドバーをフォルダ構造から自動で作るツールもありますが、MkDocsはmkdocs.ymlのnavに直接書きます。手間が一度増える代わりに、順序とラベルを完全にコントロールできます。
site_name: 製品マニュアル
theme:
name: material
nav:
- ホーム: index.md
- はじめに: getting-started.md
- 設定: configuration.md左側のラベルがサイドバーに見える名前で、右側がdocsの下のファイルパスです。navに書かなかったファイルはサイドバーに現れないので、下書きを隠しておくのも簡単です。
セクションでまとめる #
項目が増えたらまとめる必要があります。navをネストすると、そのままサイドバーのセクションになります。
nav:
- ホーム: index.md
- ガイド:
- はじめに: guide/getting-started.md
- 設定: guide/configuration.md
- 応用:
- プラグイン: advanced/plugins.mdガイドと応用は展開できるまとまりになり、その下に記事が入ります。ファイルをどのフォルダに置こうと、サイドバーの構造はnavが決めます。
見え方を整える — テーマ機能 #
Materialはナビゲーションの動作をtheme.featuresでオンにします。ドキュメントの規模に合わせて選べばよいです。
theme:
name: material
features:
- navigation.sections # セクションを展開した状態でまとめて表示
- navigation.top # トップへ戻るボタン
- toc.integrate # 右側の目次をサイドバーに統合
- search.suggest # 検索語のオートコンプリートnavigation.tabsを足すと最上位のセクションが上部のタブに上がり、navigation.expandはすべてのセクションを最初から展開します。ドキュメントが浅ければタブが、深ければ展開がよく合います。
検索 #
うれしいことに、検索を別途付ける必要はありません。Materialは内蔵検索をデフォルトでオンにしておき、ビルド時点でインデックスを作って静的ファイルとして一緒にデプロイします。サーバーが要りません。
一つだけ手を入れるところは日本語です。デフォルトの分割は空白を基準に単語を分けますが、日本語は単語が空白で区切られないため、検索がうまく引っかからないことがあります。searchプラグインのseparatorを調整して、より細かく区切ります。
plugins:
- search:
separator: '[\s\-]+'まとめ #
この記事では、navでサイドバーを直接設計し、Materialのナビゲーション機能をオンにし、検索を日本語に合わせて整えました。これで読者はドキュメントが増えてもサイドバーで位置をつかみ、検索ですぐに目的の場所へたどり着けます。
次回はコンテンツ作成を扱います。コードブロックとMermaidの図、そして注意・警告を強調するadmonitionまで、ドキュメントを読みやすくする要素を整理します。