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

フレームワーク Hugo Documentation Static Site
読了 4分

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

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

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

この記事では フォルダ構造でサイドバーを作り、weight で順序を整え、上部メニューと検索を接続する ところまで扱います。

フォルダがそのままサイドバーになる #

Hextra では、サイドバーは別途設定ファイルに書くものではなく、content の下のフォルダとファイルの構造がそのままサイドバーの階層になります。次の構造を見てみましょう。

content の構造 
content/
├─ _index.md
└─ docs/
   ├─ _index.md            # 「ドキュメント」セクション
   ├─ getting-started.md
   ├─ configuration.md
   └─ advanced/
      ├─ _index.md         # 「応用」サブセクション
      └─ plugins.md

この構造は、サイドバーで ドキュメント という項目の下に getting-started、configuration が入り、その下の 応用 項目がさらに plugins を抱えるツリーとして現れます。ドキュメントを増やす作業が、そのままフォルダを整える作業になるわけです。

セクションを作る — _index.md #

フォルダをサイドバーの一つのまとまり(セクション)にする鍵は _index.md です。フォルダに _index.md があると、Hugo はそのフォルダを一つのセクションとして扱い、サイドバーに展開できる項目として表示します。

セクション全体に共通設定を適用するときは cascade を使います。たとえば docs の下のすべてのページに Hextra のドキュメントレイアウトを適用するには、次のように書きます。

content/docs/_index.md 
---
title: ドキュメント
cascade:
  type: docs
---

cascade で下ろした設定は配下のすべてのページに適用されるので、ページごとに同じ値を繰り返し書く必要がありません。

順序を決める — weight #

サイドバーの既定の並び順は、ドキュメントの流れとうまく合いません。マニュアルは「インストール → 設定 → 応用」のように読む順序が決まっているのに、既定値はその順序を知らないからです。順序は各ページの weight で明示します。数字が小さいほど上に来ます。

content/docs/getting-started.md 
---
title: はじめに
weight: 1
---

configuration.md に weight: 2、その次の記事に weight: 3 を与えるという要領で、読む順序に番号を振ればよいです。あとで記事の間に新しい記事を挟む場合に備えて、10、20、30 のように空けておくと便利です。

サイドバーを整える — 展開と除外 #

深いツリーは既定で折りたたまれています。特定のセクションを最初から展開しておくには、そのセクションの _index.md に次を書きます。

既定で展開する 
---
title: ドキュメント
sidebar:
  open: true
---

まだ公開したくない記事は draft: true にしておくと、本番ビルドから外れます。サイドバーには残しつつ検索結果からだけ外したい場合は excludeSearch: true を使います。

検索から除外 
---
title: 内部メモ
excludeSearch: true
---

上部メニュー — navbar #

サイドバーがドキュメント内部の道なら、上部メニュー(navbar)はサイト全体の大きな枝分かれです。hugo.yaml の menu.main に項目を書きます。

hugo.yaml — 上部メニュー 
menu:
  main:
    - name: ドキュメント
      pageRef: /docs
      weight: 1
    - name: 検索
      weight: 2
      params:
        type: search

pageRef はサイト内のパスを指し、外部リンクが必要なら url を代わりに使います。検索 項目のように params.type: search を与えると、その位置に検索ボックスが入ります。

検索を接続する #

Hextra は、別途のサービスなしで動作する検索を標準で内蔵しています。FlexSearch がビルド時にドキュメントのインデックスを作り、静的ファイルとして一緒にデプロイするので、サーバーや外部 API が不要です。hugo.yaml でオン・オフできます。

hugo.yaml — 検索 
params:
  search:
    enable: true
    type: flexsearch
    flexsearch:
      index: content

一点押さえておきたいのは日本語検索です。FlexSearch の既定の分割方式は英語のような分かち書きの言語に合わせられているため、日本語は単語の途中から検索すると引っかかりにくいことがあります。実際のドキュメントで検索品質が物足りなければ、分割オプションを調整するか、規模の大きい多言語ドキュメントなら Pagefind のような代替を #6 で一緒に見ていきます。

まとめ #

この記事では、フォルダ構造でサイドバーを作り、weight で順序を整え、上部メニューと内蔵検索を接続しました。これで読者は、ドキュメントが増えてもサイドバーで位置を見当づけ、検索ですぐに探しにいけます。

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

X