Astro 製ドキュメントテーマの Starlight を導入する

## この記事の概要

Starlight は Astro を用いて作られたドキュメント用の仕組みです。
[Astro の公式ドキュメント](https://docs.astro.build/en/getting-started/)も Starlight を用いて作られています。

使い方を調べてみたいので、備忘録がてら記事にします。

## セットアップ

公式ドキュメントには npm, yarn, pnpm でのコマンドが紹介されていました。
今回は pnpm で進めます。[^pnpm]

[^pnpm]: 自分は最近 bun を使っているのでそちらを試したところ、初回起動にも関わらず画像が表示されませんでした。そのため今回は pnpm を使っています。大した情報でもありませんが念の為。

```sh
pnpm create astro --template starlight
```

対話型でオプションを選択しました。

```sh      
  astro   Launch sequence initiated.

   dir   Where should we create your new project?
         ./project-name
      ◼  tmpl Using starlight as project template
 ██████  Template copying...

  deps   Install dependencies?
         Yes
 ██████  Installing dependencies with pnpm...

    ts   Do you plan to write TypeScript?
         Yes

   use   How strict should TypeScript be?
         Strict
 ██████  TypeScript customizing...

   git   Initialize a new git repository?
         Yes
 ██████  Git initializing...

  next   Liftoff confirmed. Explore your project!

         Enter your project directory using cd ./project-name
         Run pnpm dev to start the dev server. CTRL+C to stop.
         Add frameworks like react or tailwind using astro add.

         Stuck? Join us at https://astro.build/chat

╭─────╮  Houston:
│ ◠ ◡ ◠  Good luck out there, astronaut! 🚀
╰─────╯
```

起動します。

```sh
pnpm dev
```

まずは無事に表示されました。

![](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/214677/edeb5c7e-5957-e120-2084-4f74c6bdf5c5.png)

## ドキュメントの基本的な書き方

次に、Markdown を用いて具体的なドキュメントを書いていきます。
はじめから `src/content/docs` に Markdown ファイルが格納されています。

```sh
.
├── README.md
├── astro.config.mjs
├── package.json
├── pnpm-lock.yaml
├── public
│   └── favicon.svg
├── src
│   ├── assets
│   │   └── houston.webp
│   ├── content
│   │   ├── config.ts
│   │   └── docs
│   │       ├── guides
│   │       │   └── example.md
│   │       ├── index.mdx
│   │       └── reference
│   │           └── example.md
│   └── env.d.ts
└── tsconfig.json
```

フォルダの階層にあわせて左サイドバーにナビゲーションが生成されています。

- Guides
    - Example Guide
- Reference
    - Example Reference

![localhost_4321_guides_example_.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/214677/7cf163f0-4b4a-ab4e-e02a-e77c9d1869dd.png)

もっと階層を深くすることも可能です。
後半で説明します。

基本的には Markdown でドキュメントを書くつもりであれば大丈夫です。

https://starlight.astro.build/guides/authoring-content/

一部独自の記法があるので紹介します。

まずは、余談的な要素です。
Qiita にも似たような記法がありますね。
タイトルを変えたいときは `:::note[別のタイトル]` のように記載すれば OK です。

```markdown
:::note
補足説明的なテキスト
:::

:::tip
tips に関するのテキスト
:::

:::caution
注意を促すテキスト
:::

:::alert
アラートのテキスト
:::
```

また、[Expressive Code](https://github.com/expressive-code/expressive-code/tree/main/packages/astro-expressive-code) を用いた拡張記法にも対応しているようです。

https://starlight.astro.build/guides/authoring-content/

## ドキュメントを拡張する

Starlight は中身が Astro なので、拡張子が `.astro` のコンポーネントを作って利用できます。

また、以下のビルトインコンポーネントもあります。

- Card
- CardGrid
- Icon
- Tabs
- TabItem
- LinkCard

https://starlight.astro.build/guides/components/

## ナビゲーション

ディレクトリ構造にあわせることも、自分で明示的に設定することもできます。

`astro.config.mjs` 内にある `sidebar` の項目で `autogenerate` を指定すればディレクトリ通りに、明示すれば順番やラベルテキスト含めて自由に作成できます。

https://starlight.astro.build/guides/sidebar/

## サイト全体の設定

最後にサイトタイトルやロゴ、説明文などの設定です。

`astro.config.mjs` の中で設定を変えられます。
最低限で言えばタイトルだけあれば OK です。

https://starlight.astro.build/reference/configuration/#configure-the-starlight-integration

## 最後に

Astro 自体の使い勝手が良いので、 Starlight への期待も高まっています。
現在は自分のポートフォリオを Astro で 1 から作っているのですが、なんならこれでも良いかもしれない……と揺らいでいる最中です。