Starlightでマニュアルを作る #1 インストールから最初のドキュメントまで

フレームワーク Starlight Documentation Static Site
読了 4分

ドキュメントを本格的に作り始めると、ほぼ例外なく同じ問題に出会います。README一枚では収まりきらないドキュメントをどこに積み上げるか、という問題です。Notionは外部公開とバージョン管理が手間で、ブログツールで作ると記事が時系列に並ぶだけでリファレンスとしては使いにくいものです。そのため多くのチームが、ドキュメントをコードのように扱う方式、すなわちDocs as Codeへと移っていきます。マークダウンで書き、Gitで管理し、静的サイトとしてデプロイする方式です。

このシリーズは、その最初の一歩である静的サイトジェネレーターでドキュメントサイトを構築する方法を扱います。ツールはStarlightです。モダンなWebフレームワークAstroの上に乗ったドキュメントテーマで、基本的にJSをほとんど送らないため軽くて速いのが強みです。検索と多言語も標準で備えています。

今回のシリーズはStarlightでマニュアルを作る全6回です。

  • #1 インストールから最初のドキュメントまで ← 今回の記事
  • #2 サイドバーと検索 — ドキュメントの情報構造を整える
  • #3 コンテンツ作成 — コードブロック、Mermaid、aside
  • #4 Cloudflare Pagesでデプロイしてドメインを接続する
  • #5 多言語とバージョン管理
  • #6 メンテナンス — 検索、アクセシビリティ、ドキュメント文化

今回の記事は、Starlightが何を準備物として要求するのか、そして新しいサイトを作って開発サーバーで最初のドキュメントを表示するところまでを、実際に動かしながら締めくくります。

準備物 — Node.js #

StarlightはAstroの上で動くツールなので、準備物はNode.js 18バージョン以上です。インストール後にバージョンを確認します。

バージョン確認 
node --version

Docusaurusと同じくJavaScriptエコシステムの上で動きますが、Astroは必要な箇所だけにJSを乗せる構造なので、成果物がより軽くなります。

新しいサイトを作る #

Astroの生成ツールにStarlightテンプレートを指定すると、ドキュメントサイトの土台が一度に作られます。

新しいサイトを生成 
npm create astro@latest -- --template starlight

対話形式でフォルダ名と依存関係のインストール有無を尋ね、終わるとすぐに始められる形になります。

最初のドキュメントを表示する #

作られたフォルダに入って開発サーバーを起動します。

開発サーバーの実行 
cd my-docs
npm run dev

ブラウザでhttp://localhost:4321を開くと、Starlightのレイアウトに標準のドキュメントが表示されます。ファイルを直すと画面が即座に更新されます。

サイトタイトルのような設定は、astro.config.mjsのStarlight統合で指定します。

astro.config.mjs 
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';

export default defineConfig({
  integrations: [
    starlight({ title: '製品マニュアル' }),
  ],
});

フォルダ構造を理解する #

生成された構造のうち、すぐに知っておくべきはドキュメントが入るフォルダと設定ファイルです。

フォルダ構造 
my-docs/
├─ astro.config.mjs       # Astro + Starlight 設定
├─ src/
│  └─ content/
│     └─ docs/            # ドキュメント本文 (ここを埋めます)
│        ├─ index.mdx     # 最初の画面
│        └─ guides/example.md
├─ public/                # 画像などの静的ファイル
└─ dist/                  # npm run build の成果物 (デプロイ用)

ドキュメントを増やす作業は、結局のところsrc/content/docsの下にマークダウンファイルを足す作業です。Starlightはこのフォルダ構造をもとにサイドバーを自動で作り、必要なら自分で定義することもできます。その方法は次回で扱います。

まとめ #

今回の記事ではNode.jsを準備し、create astroでStarlightサイトを生成して、開発サーバーで最初のドキュメントを表示するところまで終えました。Nodeベースでありながら成果物が軽く、検索まで標準で付いてくる点がStarlightの強みです。

次回はサイドバーと検索を扱います。ドキュメントが数十編に増えても読者が道に迷わないよう、情報構造を設計する段階です。

X