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

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

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

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

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

今回の記事は、サイドバーを自動・手動で構成し、組み込みの検索を確認するところまで扱います。

サイドバーは設定で定義する #

Starlightのサイドバーはastro.config.mjsのStarlight統合の中で指定します。二つの方式があります。一つ目はフォルダに沿って自動で作る方式です。

astro.config.mjs — 自動生成 
starlight({
  title: '製品マニュアル',
  sidebar: [
    { label: 'ガイド', autogenerate: { directory: 'guides' } },
  ],
})

guidesフォルダ内のドキュメントがガイドのまとまりとして自動整列されます。各記事の順序はフロントマターのsidebar.orderで調整します。

直接定義する #

順序と構造を完全に制御したいなら、項目を直接書きます。

astro.config.mjs — 直接定義 
sidebar: [
  { label: 'はじめに', link: '/intro/' },
  {
    label: 'ガイド',
    items: [
      { label: 'インストール', link: '/guides/install/' },
      { label: '設定', link: '/guides/config/' },
    ],
  },
]

labelがサイドバーに見える名前で、linkがドキュメントのパスです。

検索 — 標準で組み込み #

良い知らせは、検索を別途付ける必要がないことです。StarlightはPagefindを標準で組み込んでいます。ビルド時点でインデックスを作って細かく分割しておき、ブラウザが検索語に必要な断片だけを受け取るので、ドキュメントが多くても軽快です。サーバーや外部サービスが不要で、韓国語を含むドキュメントも問題なく検索できます。

検索は開発サーバーでは表示されず、npm run buildでビルドした結果で動作します。インデックスがビルド成果物を走査して作られるためです。

まとめ #

今回の記事ではサイドバーを自動・手動で構成し、標準で組み込まれたPagefind検索を確認しました。検索を別途気にかけなくてよい点が、情報構造を整える作業をいっそう軽くします。

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

X