AstroのStarlightテンプレート

AstroとStarlight

AstroとStarlightを使用していく上では両方のドキュメントを見る必要がある。Starlightに従う必要があるので、こちらを中心に参照し、基礎的な部分のみAstroを参照する。

• Astro
• Starlight

フォルダ構成

フォルダの構成は以下のようになる。

• src 以下がビルド対象で、 public はそのまま使用される
• src/content/docs 以下にドキュメントを書く
• src/components で構成部品の上書き
• src/pages でページの上書き

.
├── astro.config.mjs
├── public
│   └── favicon.svg
└── src
　   ├── assets
　   │   └── houston.webp
　   ├── components
　   │   └── Sidebar.astro
　   ├── content
　   │   └── docs
　   │       ├── index.mdx
　   │       └── group
　   │           └── example.md
　   ├── content.config.ts
　   ├── pages
　   │   └── index.astro
　   ├── routeMiddleware.ts
　   └── styles
　       └── custom.css

多少 config を編集する場面はあるものの、src/content/docs 以下にドキュメントを書いていくことで、コンテンツを増やしていける。

ドキュメントの追加

src/content/docs 以下にドキュメントを追加する。この時点でドキュメント自体は認識されるが、サイドバーなどには表示されないため、別途設定が必要となる。

src/content/docs
├── guides
│   └── example.md
└── reference
　   └── example.md

テンプレートでは guides と reference サブディレクトリが存在し、それぞれ手動追加と自動検出の例となっている。

astro.config.mjs:

// @ts-check
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';

// https://astro.build/config
export default defineConfig({
  integrations: [
    starlight({
      ...
      sidebar: [
        {
          // guides以下は手動で追加する必要がある
          label: 'Guides',
          items: [
            { label: 'Example Guide', slug: 'guides/example' },
          ],
        },
        {
          // reference以下はファイルを自動検出する
          label: 'Reference',
          autogenerate: { directory: 'reference' },
        },
      ],
    }),
  ],
});