Starlightでマニュアルを作る #3 コンテンツ作成 — コードブロック、Mermaid、aside

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

#2でサイドバーと検索を使ってドキュメントの土台を整えました。今度はその中身を埋める番です。技術ドキュメントは地の文だけでは足りません。コマンドはコードブロックで、流れはダイアグラムで、注意点は目立つ箱で見せてこそ、読者は素早く読めます。

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

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

今回の記事は、コードブロックをきちんと装飾し、Mermaidでダイアグラムを描き、asideで強調する三つを扱います。

コードブロック — タイトルと行強調 #

StarlightはExpressive Codeというコードブロックエンジンを標準で備えています。おかげで別途の設定なしにタイトル・行強調・コピーボタンが使えます。コードフェンスの言語の後ろにオプションを書きます。

コードブロックにタイトルと強調 
```js title="src/app.js" {2}
function add(a, b) {
  return a + b; // この行が強調されます
}
```

titleでファイル名の帯を、{2}のように波括弧内の数字で強調する行を指定します。コピーボタンはすべてのコードブロックに自動で付きます。

ダイアグラム — Mermaid #

MermaidはStarlightのコアには含まれていません。rehype-mermaidのようなプラグインをastro.config.mjsに加えると、mermaidフェンスがダイアグラムとしてレンダリングされます。

astro.config.mjs — Mermaid 追加 
import rehypeMermaid from 'rehype-mermaid';

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

これで、他のツールと同じやり方でダイアグラムをコードとして書けます。

Mermaid フローチャート 
```mermaid
flowchart LR
  A[記事作成] --> B[ビルド] --> C[デプロイ]
```

aside — 注意と警告の強調 #

「これは必ず読まなければならない」という内容は、地の文の間に埋もれてはいけません。Starlightは強調の箱をasideと呼び、標準で組み込んでいます。コロン三つで囲んで種類を書きます。

aside の書き方 
:::caution[注意]
本番に適用する前に、必ずバックアップを先に行ってください。
:::

種類にはnote、tip、caution、dangerがあり、それぞれ色とアイコンが異なるため、情報・注意・危険を視覚的に区別します。

タブで分ける #

オペレーティングシステムごとのコマンドのように枝分かれする内容は、タブで見せます。Starlightが提供するコンポーネントをMDXファイルから読み込んで使います。

タブで分ける 
import { Tabs, TabItem } from '@astrojs/starlight/components';

<Tabs>
  <TabItem label="macOS">brew install our-product</TabItem>
  <TabItem label="Windows">winget install our-product</TabItem>
</Tabs>

まとめ #

今回の記事ではExpressive Codeのコードブロック、プラグインで加えたMermaidのダイアグラム、そして注意・警告を強調するasideとタブまで扱いました。コードブロックとasideが標準で強力で、設定が少ない点がStarlightの長所です。

次回はこのドキュメントを世に送り出します。Cloudflare Pagesでデプロイしてカスタムドメインを接続し、誰でもアドレスでアクセスできるようにする過程を整理します。

X