この記事の概要
Starlight は Astro を用いて作られたドキュメント用の仕組みです。
Astro の公式ドキュメントも Starlight を用いて作られています。
使い方を調べてみたいので、備忘録がてら記事にします。
セットアップ
公式ドキュメントには npm, yarn, pnpm でのコマンドが紹介されていました。
今回は pnpm で進めます。1
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 から作っているのですが、なんならこれでも良いかもしれない……と揺らいでいる最中です。
-
自分は最近 bun を使っているのでそちらを試したところ、初回起動にも関わらず画像が表示されませんでした。そのため今回は pnpm を使っています。大した情報でもありませんが念の為。 ↩