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

この記事の概要

Starlight は Astro を用いて作られたドキュメント用の仕組みです。
Astro の公式ドキュメントも Starlight を用いて作られています。

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

セットアップ

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

pnpm create astro --template starlight

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

  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! 🚀
╰─────╯

起動します。

pnpm dev

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

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

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

.
├── 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

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

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

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

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

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

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

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

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

また、Expressive Code を用いた拡張記法にも対応しているようです。

ドキュメントを拡張する

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

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

• Card
• CardGrid
• Icon
• Tabs
• TabItem
• LinkCard

ナビゲーション

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

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

サイト全体の設定

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

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

最後に

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

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