前回まで

ドキュメントサイトをつくるためのAstro公式テンプレート「Starlight」で作成したサイトについて、GitHubを使用してチームで運用する方法と、デプロイについて解説しました。

今回はStarlightの構造を把握し、ドキュメントの追加方法とナビゲーションについて見ていきましょう。

ドキュメントの管理

まずはドキュメントサイトのディレクトリ構造と保存場所、ファイル形式を押さえましょう。

ドキュメントサイトのディレクトリ構造

Starlightでは、各ドキュメントファイルをsrc/content/docs/ディレクトリ以下に配置します。このディレクトリ内に格納したファイルが自動的にWebページになります。

ドキュメントファイルの形式は、シンプルなMarkdown（.md）または、コンポーネントを利用できるMDX（.mdx）のどちらでも利用できます。新たに追加する際はドキュメントでコンポーネントが必要かどうかで選びましょう。

最初はMarkdownで作成しておき、必要になったらあとからMDXに変更することもできます。その場合は拡張子を.mdxに変えるだけで、ビルトインのコンポーネントや独自のコンポーネントをインポートできるようになります。

各ドキュメントファイルには、YAMLで書かれたフロントマターが含まれています。guides/example.mdのフロントマターではtitleとdescriptionが用意されていて、ページのtitle要素やメタディスクリプションで使われたり、見出しとしても使われます。

---
title: Example Guide
description: A guide in my new Starlight docs site.
---

フロントマターの下には通常のMarkdownでドキュメントの内容を書いていくだけです。

ドキュメントの追加と削除

新しいドキュメントを追加したければ、src/content/docs/以下にドキュメントファイルを作成しましょう。例として、new.mdというファイルを作成し、以下の内容を追加します。

---
title: "新しいページ"
description: "Starlightに追加した新しいページ"
---

Starlightをより効果的に活用するためのテクニックを紹介します。

このファイルをまずは、referenceディレクトリに置いてみると、自動的にサイドナビゲーションにも追加されます。サイドナビゲーションがあるページへは、トップページの「Example Guide →」ボタンをクリックすると移動できます。

サイドナビゲーションの「Reference」の配下に「新しいページ」が追加されているのがわかります。

次に、さきほどのnew.mdファイルをguidesディレクトリに移動してみましょう。すると今度は、サイドナビゲーションに自動では追加されません。これは、astro.config.mjsのsidebar設定において、guidesディレクトリにautogenerateが指定されていないためです。

ただしhttp://localhost:4321/guides/newに直接アクセスすればページ自体は表示されるので、「ページが作成されないわけではない」ことに注意しましょう。

このようにStarlightでは、ファイルをdocs以下に置くだけで、そのパスに対応するページが自動で生成されます。サイドナビゲーションに表示されるかどうかは、設定で調整できます。次の節では、この仕組みについて詳しく見ていきます。

なお、該当のドキュメントファイルを削除すれば、自動的にページも削除されます。

サイドナビゲーションの設定

サイドナビゲーションはユーザーの主な移動手段ですので、その仕組みについて理解し、わかりやすく表示できるようにしていきましょう。

サイドナビゲーションはastro.config.mjsのStarlightインテグレーションの設定の通りに表示されます。

デフォルトでは次のようになっています。

export default defineConfig({
  integrations: [
    starlight({
      title: 'My Docs',
      social: {
        github: 'https://github.com/withastro/starlight',
      },
      sidebar: [
        {
          label: 'Guides',
          items: [
            // Each item here is one entry in the navigation menu.
            { label: 'Example Guide', slug: 'guides/example' },
          ],
        },
        {
          label: 'Reference',
          autogenerate: { directory: 'reference' },
        },
      ],
    }),
  ],
});

sidebarがサイドナビゲーションの設定です。ここに書かれた設定がそのままサイドナビゲーションとして表示されます。まずは理解するため最小限の設定にしてみましょう。

基本的に、リンクとして並べたいページのパスをslugとして指定して並べていくだけです。そうすると、各ページのtitleを利用してリンクが並びます。

      sidebar: [
        { slug: 'guides/example' },
        { slug: 'guides/new' },
      ],

ページ名が長くてナビゲーション上見にくくなってしまうなどの理由で、ページ名は変えずにナビゲーション上だけ表示を変えたいという場合があるかもしれません。その場合はlabelでナビゲーション上の表示名を設定します。

      sidebar: [
        { label: 'サンプルガイド', slug: 'guides/example' },
        { slug: 'guides/new' },
      ],

グループ化

ページが増えてくると、グループ化して整理したいと考えます。labelとitemsの配列をもつオブジェクトを用意することで、ページをグループ化できます。itemsの配列に入れられるのはslugをもつオブジェクトなど、sidebarに入れているこれまでのオブジェクトと同じです。

デフォルトの設定では次のようにGuides（ガイド）としてExample Guideがひとつだけ入ったグループとして設定されていました。

        {
          label: 'Guides',
          items: [
            // Each item here is one entry in the navigation menu.
            { label: 'Example Guide', slug: 'guides/example' },
          ],
        },

頻繁にページが追加されるグループでは、毎回設定するのではなく、自動的にサイドナビゲーションに追加されて欲しいと思うかもしれません。

autogenerateを使うと、特定のディレクトリにあるファイルすべてを並べることができます。これはデフォルトではreferenceディレクトリに設定されていたものです。

        {
          label: 'Reference',
          autogenerate: { directory: 'reference' },
        },

最初に新たなドキュメントファイルnew.mdを作成したとき、referenceに配置すると自動的にナビゲーションに追加されたのは、この設定がされていたためです。

自動生成の注意点

自動的にページを追加してくれる、大変便利なautogenerateですが、ナビゲーションの並び順はStarlight公式ドキュメントにおいてアルファベット順となっていて日本語の順序については記載がありません。

これを制御するために各ページのフロントマターにsidebar.orderで順序を指定することもできますが、順序を指定したいなら自動ではなく、上記のようにautogenerateを使わず、手動で管理するほうがよいでしょう。

また、autogenerateを設定してしまうと、ラベル名も各ドキュメントファイルのtitleが使われます。これも各ファイルのフロントマターでsidebar.labelを指定するという方法もありますが、全体のラベル名を調整するのなら他のページのラベルも一元管理できる、手動でのサイドバー設定のほうが扱いやすいように思います。

ここまでのまとめ

今回は、ファイルの管理と、サイドバーナビゲーションの仕組みについて解説しました。

次回はドキュメントファイルの中身の編集とサイト全体の設定やトップページについて説明します。