Astro Starlight インストール手順と初期構築依頼

1. 目的

Astro Starlight を使って、Markdown を追加するだけで運用できる日本語・英語対応のナレッジベースを構築する。

最終的に目指す構成は以下。

• Astro Starlight
• Markdown / MDX
• 日本語 /ja/
• 英語 /en/
• 日本語と英語で独立したサイドバー
• Pagefind による言語別検索
• ディレクトリ構造からサイドバーを自動生成
• index.mdx + DirectoryIndex.astro によるページ一覧
• 一覧の表示階層を depth={N} または recursive で指定
• 既存 Markdown の title を前処理で自動補完
• GitHub 管理
• Cloudflare Pages 等への静的デプロイ
• Windows ネイティブ開発
• WSL / Docker は必須にしない

---

2. Windows での Astro Starlight インストール

2.1 Node.js の準備

Node.js は Windows ネイティブでもいいが、
複数バージョンを切り替えたい場合は nvm-windows を利用する。

Node.js / npm が利用できることを確認する。

winget search nvm
winget install CoreyButler.NVMforWindows

# 別ターミナル
nvm version
nvm --version

nvm install 22
nvm use 22

where.exe node
where.exe npm

---

2.2 Starlight プロジェクトを作成

作業ディレクトリへ移動する。

例:

cd "P:\git"

Starlight テンプレートで Astro プロジェクトを作成する。

npm create astro@latest -- --template starlight

対話では、例えば以下のように設定する。

Where should we create your new project?
./markdown-site

Install dependencies?
Yes

Initialize a new git repository?
Yes

---

2.3 基本コマンド

開発サーバー:

npm run dev

本番ビルド:

npm run build

本番ビルドのローカル確認:

npm run preview

Astro のチェック:

npx astro check

---

3. インストール後に Codex へ依頼する内容

以下の依頼を 1 回で渡し、これまで段階的に行っていた修正を最初からまとめて実装する。

---

Codex 依頼文

以下の Astro Starlight プロジェクトを、Markdown を追加するだけで運用できる日本語・英語対応ナレッジベースとして初期構築してください。

最重要目標は、

通常の記事追加では Markdown ファイルを追加するだけで、サイドバー・一覧ページ・検索へ自動反映されること

です。

不要な大規模独自実装は避け、Astro / Starlight の標準機能を優先し、必要な箇所だけ小さく拡張してください。

---

1. 基本構成

静的サイトジェネレーター:

Astro Starlight

コンテンツ:

Markdown / MDX

言語:

/ja/   日本語
/en/   English

日本語と英語は完全な翻訳ミラーにはしません。

日本語と英語で、

• コンテンツ構成
• カテゴリ
• サイドバー

が異なってもよい設計にしてください。

---

2. 推奨ディレクトリ構成

以下を基本としてください。

src/
├── components/
│   ├── DirectoryIndex.astro
│   ├── Sidebar.astro
│   ├── SidebarTree.astro
│   └── 必要な補助コンポーネント
│
├── styles/
│   └── custom.css
│
├── content/
│   └── docs/
│       ├── ja/
│       │   ├── index.mdx
│       │   ├── tech/
│       │   │   ├── index.mdx
│       │   │   ├── aws/
│       │   │   │   ├── index.mdx
│       │   │   │   ├── control-tower.md
│       │   │   │   └── organizations.md
│       │   │   └── terraform/
│       │   │       ├── index.mdx
│       │   │       └── state.md
│       │   └── english/
│       │       └── index.mdx
│       │
│       └── en/
│           ├── index.mdx
│           └── tech/
│               ├── index.mdx
│               └── aws/
│                   ├── index.mdx
│                   └── control-tower.md
│
├── content.config.ts
└── ...

scripts/
└── normalize-content.mjs

astro.config.mjs
package.json
README.md

実際の Starlight 推奨構成に合わせた調整は可。

---

3. Markdown / MDX の使い分け

通常記事:

*.md

カテゴリ・ディレクトリ一覧:

index.mdx

例:

aws/
├── index.mdx
├── control-tower.md
├── organizations.md
└── vpc.md

通常記事では独自コンポーネントを極力使わないでください。

---

4. 日本語 / 英語 locale

Starlight の locale 機能を利用してください。

概念:

locales: {
  ja: {
    label: '日本語',
    lang: 'ja',
  },
  en: {
    label: 'English',
    lang: 'en',
  },
}

以下を満たしてください。

/ja/ → <html lang="ja">
/en/ → <html lang="en">

locale 設定は Pagefind の言語別検索にも利用します。

---

5. 右上の LanguageSelect は非表示

日本語と英語は完全ミラーではないため、右上の「日本語 / English」切り替え UI は表示しないでください。

ただし locale 自体は削除しないでください。

つまり、

locales       → 維持
HTML lang     → 維持
Pagefind      → 維持
LanguageSelect UI → 非表示

Starlight の component override 等、標準的な方法を利用してください。

CSS や JavaScript で後から雑に消す方法は避けてください。

---

6. サイドバーは日本語 / 英語で完全分離

日本語側は src/content/docs/ja/ のみから生成。

英語側は src/content/docs/en/ のみから生成。

例えば日本語:

Technology
  AWS
  Terraform

英語学習
健康
投資

英語:

Technology
  AWS
  Cloud Security

Finance

といった異なる構造を許容してください。

日本語にしか存在しない、

/ja/english/

を英語サイドバーへ表示しないでください。

通常記事追加時に astro.config.mjs へ 1 ページずつ追加する方式にはしないでください。

---

7. サイドバーはディレクトリ構造から自動生成

例えば、

src/content/docs/ja/tech/aws/vpc.md

を追加すると、自動的に日本語側の AWS 配下に表示してください。

新規カテゴリ:

src/content/docs/ja/tech/kubernetes/
├── index.mdx
└── networking.md

を追加した場合も自動的にサイドバーへ反映してください。

---

8. サイドバーのディレクトリノード動作

8.1 index.mdx がある場合

例えば、

aws/
├── index.mdx
├── control-tower.md
└── organizations.md

ならサイドバーは、

▼ AWS
    Control Tower
    Organizations

としてください。

index.mdx を子項目として重複表示しないでください。

AWS の文字部分をクリックすると、

/ja/tech/aws/

へ遷移し、その一覧ページを表示してください。

同時に AWS ツリーを展開状態にしてください。

展開アイコンはツリーの開閉に使ってください。

---

8.2 index.mdx がない場合

例えば、

backup/
├── backup-3-2-1-rule.md
└── another.md

のように index.mdx がない場合は、ディレクトリ名をリンクにしないでください。

期待:

▶ backup

backup をクリックした場合:

• ページ遷移しない
• 現在ページはそのまま
• 404 にしない
• backup ツリーだけ展開 / 折りたたみ

としてください。

Sidebar 生成時に、そのディレクトリに対応する index.mdx が存在するかを自動判定してください。

---

9. URL に応じて祖先サイドバーを自動展開

現在ページまたはその祖先ディレクトリは、自動的に展開状態にしてください。

例:

/ja/tech/

では:

▼ Technology
  ▶ AWS
  ▶ Terraform

例:

/ja/tech/aws/

では:

▼ Technology
  ▼ AWS
    Control Tower
    Organizations
  ▶ Terraform

例:

/ja/tech/aws/control-tower/

でも:

▼ Technology
  ▼ AWS
    Control Tower
    Organizations

となること。

Control Tower のみ active 表示し、祖先は open のみとしてください。

展開状態は可能な限り現在 URL を基準にしてください。

以下でも正しく展開される必要があります。

• 直接 URL を開く
• ブックマーク
• リロード
• 戻る / 進む
• Pagefind 検索結果から直接開く

---

10. /ja/ /en/ トップでもサイドバーを常時表示

トップページにも通常の Starlight レイアウトを使ってください。

以下ではサイドバーを表示してください。

/ja/
/en/

template: splash は使用しないでください。

カテゴリトップも原則として通常レイアウトにしてください。

---

11. Previous / Next を非表示

このサイトは順番に読むチュートリアルではなく、検索・カテゴリ一覧からアクセスするナレッジベースです。

ページ下部の Previous / Next は無効化してください。

Starlight の標準設定を利用してください。

例:

pagination: false

---

12. 右側のページ内目次は維持

PC 表示時の右側 TOC は残してください。

ただし、Starlight がページ先頭へのリンクとして自動追加する 概要 / Overview は非表示にしてください。

Markdown 本文に、

## 概要

がある場合は、これだけを TOC に表示してください。

期待:

目次

概要
なぜ必要か
「2」の意味

以下のように重複させないでください。

概要
概要

CSS で最初の項目を雑に消したり、「概要」という日本語文字列に依存して削除したりせず、Starlight の TOC 構造上の overview 項目を適切に除外してください。

英語でも同じ挙動にしてください。

---

13. DirectoryIndex.astro

カテゴリの index.mdx は、以下のような最小記述で利用できるようにしてください。

---
title: AWS
description: AWS に関する記事一覧です。
---

import DirectoryIndex from '.../DirectoryIndex.astro';

<DirectoryIndex />

可能なら import パスも簡略化してください。

DirectoryIndex は現在のディレクトリを自動判定し、ページ一覧を表示してください。

---

14. DirectoryIndex の表示階層

以下をサポートしてください。

<DirectoryIndex />

または:

<DirectoryIndex depth={1} />

→ 直下 1 階層

<DirectoryIndex depth={2} />

→ 2 階層下まで

<DirectoryIndex depth={3} />

→ 3 階層下まで

<DirectoryIndex recursive />

→ 配下すべて

recursive と depth が同時指定された場合は recursive を優先し、全階層としてください。

既存の <DirectoryIndex /> は直下 1 階層のままにしてください。

---

15. DirectoryIndex の対象と並び順

以下を満たしてください。

• 現在ページ自身の index.mdx は除外
• Markdown / MDX を自動取得
• sidebar.order があればそれを優先
• 同順位なら title 順
• description を表示
• lastUpdated があれば表示可能
• tags があれば表示可能

サブディレクトリのカテゴリトップをどのように表示するかは、現在の構造と整合する自然な実装にしてください。

---

16. DirectoryIndex はカードではなくリスト表示

カード UI は使用しないでください。

以下のようなシンプルなリストにしてください。

AWS Control Tower
AWS Control Tower の基本構成について解説します。

AWS Organizations
AWS Organizations と OU について解説します。

IAM Identity Center
IAM Identity Center の管理方法について解説します。

要件:

• カード背景なし
• 枠線なし
• border-radius なし
• タイトルはリンク
• description はタイトル下
• 記事間に適度な余白または薄い区切り
• Starlight 標準テーマになじむ
• ダークモード対応

---

17. section / category は frontmatter に書かない

分類はディレクトリ構造から自動判定してください。

例えば:

src/content/docs/ja/tech/aws/control-tower.md

なら内部的に:

language = ja
section  = tech
category = aws

と判定してください。

例えば:

src/content/docs/en/finance/trading/risk.md

なら:

language = en
section  = finance
category = trading

としてください。

浅い階層では未定義で構いません。

例:

src/content/docs/ja/english/index.mdx

language = ja
section  = english
category = undefined

frontmatter に、

section:
category:

を毎回書かせないでください。

ディレクトリ構造と frontmatter の二重管理を避けてください。

将来 Pagefind filter 等で必要なら、パスから都度算出してください。

---

18. 通常 Markdown の frontmatter は最小限

基本:

---
title: AWS Control Tower
description: AWS Control Towerについて解説します。
---

必要な場合のみ:

sidebar: { order: 10 }

や:

tags:
  - AWS

を使用できるようにしてください。

Astro / Starlight 固有 frontmatter は必要最小限にしてください。

---

19. 既存 Markdown の title 自動補完

既存 Markdown を大量に取り込めるように、前処理スクリプトを追加してください。

コマンド:

npm run normalize-content

対象:

src/content/docs/**/*.md
src/content/docs/**/*.mdx

title がない場合の優先順位:

1. frontmatter title
2. 最初の H1
3. 最初の H2
4. ファイル名から拡張子を除いた値

---

20. frontmatter title と本文 H1 を両立させる

元:

# バックアップの「3-2-1ルール」メモ

## 概要

normalize 後:

---
title: バックアップの「3-2-1ルール」メモ
---

# バックアップの「3-2-1ルール」メモ

## 概要

としてください。

title はサイドバー・一覧・SEO 用のメタデータ、本文 H1 はページ内で表示する見出しとして扱ってください。

Starlight が自動表示する frontmatter title の PageTitle は component override で表示しないでください。これによりタイトルの二重表示を避けつつ、既存 Markdown の本文 H1 を維持します。

本文 H1 は従来の Starlight PageTitle に近い見た目にしてください。

• 本文カラムの左右端まで伸びる 1px の薄い下線を付ける
• 下線と H1 の間に適度な余白を取る
• H2 に独自の下線を追加せず、Starlight 標準の見た目を維持する

以下の規則にしてください。

frontmatter title あり
→ 本文 H1 は変更しない

title なし + H1 あり
→ H1 から title を生成するが、本文 H1 は残す

title なし + H1 なし + H2 あり
→ H2 から title を生成するが H2 は残す

H1/H2 なし
→ ファイル名から title

としてください。

---

21. normalize-content の安全要件

以下を満たしてください。

• .md / .mdx 対象
• index.mdx も対象
• 既存 title があれば変更しない
• 既存 frontmatter を壊さない
• title 以外を不用意に変更しない
• コードブロック内の # / ## は見出しと判定しない
• frontmatter 内の文字列を見出し判定しない
• 日本語 UTF-8 を壊さない
• Windows の CRLF / LF を可能な限り維持
• BOM があっても可能なら壊さない
• 冪等にする
• 2 回目以降の実行で不要な diff を発生させない

---

22. normalize-content の dry-run

以下を実装してください。

npm run normalize-content -- --dry-run

変更予定ファイルと生成される title が確認できるようにしてください。

例:

Would update:
- src/content/docs/ja/tech/backup/backup-3-2-1-rule.md
  title: バックアップの「3-2-1ルール」メモ
  source: H1
  preserve source H1: yes

1 file would be updated.

---

23. package.json

以下を追加してください。

{
  "scripts": {
    "normalize-content": "node scripts/normalize-content.mjs"
  }
}

実際のファイル名に合わせて調整可。

不要な依存は増やさないでください。

ただし YAML frontmatter を安全に扱うため一般的な軽量ライブラリが有効なら、その理由を説明した上で利用して構いません。

---

24. Pagefind

Starlight 標準 Pagefind を利用してください。

外部検索サービスは利用しません。

日本語:

/ja/

では日本語コンテンツだけ検索。

英語:

/en/

では英語コンテンツだけ検索。

HTML lang と Pagefind の多言語インデックスを正しく利用してください。

---

25. 将来の Pagefind filter を考慮

将来的に、

サイト全体
Technology
AWS
Terraform
Kubernetes

のような絞り込みを追加できる設計にしてください。

ただし今回 filter UI の実装は不要です。

以下はパスから取得できる状態にしてください。

language
section
category

---

26. 画像運用

記事・カテゴリの近くに images ディレクトリを置けるようにしてください。

例:

aws/
├── control-tower.md
└── images/
    ├── control-tower.drawio
    ├── control-tower.svg
    └── control-tower-console.webp

方針:

*.drawio → 編集原本
*.svg    → 構成図の Web 表示
*.webp   → スクリーンショット等
*.png    → 必要に応じて利用

Markdown から相対参照できること。

サイト共通画像は src/assets/ 等の適切な場所を利用してください。

---

27. Astro Dev Toolbar

ローカル npm run dev で表示される Astro Dev Toolbar は開発用なので、無理に削除しないでください。

本番ビルドでは通常表示されないため、そのままで構いません。

---

28. README

README に以下を記載してください。

ローカル起動

npm install
npm run dev

build

npm run build

preview

npm run preview

normalize

npm run normalize-content

dry-run

npm run normalize-content -- --dry-run

新しい記事追加

例:

src/content/docs/ja/tech/aws/vpc.md

最低限:

---
title: VPC
description: VPCについて解説します。
---

既存 Markdown 取り込み

Markdown をコピーした後、

npm run normalize-content

を実行すること。

新カテゴリ

例:

src/content/docs/ja/tech/kubernetes/
├── index.mdx
└── networking.md

index.mdx / DirectoryIndex

<DirectoryIndex />
<DirectoryIndex depth={2} />
<DirectoryIndex depth={3} />
<DirectoryIndex recursive />

の違い。

index.mdx がないディレクトリ

サイドバー上ではグループとして扱い、クリックしても遷移せず開閉だけ行うこと。

---

29. 動作確認用コンテンツ

最低限、日本語・英語でテストできるサンプルを用意してください。

日本語:

/ja/
/ja/tech/
/ja/tech/aws/
/ja/tech/aws/control-tower/
/ja/tech/terraform/
/ja/english/

英語:

/en/
/en/tech/
/en/tech/aws/
/en/tech/aws/control-tower/

さらに index.mdx がないテスト用ディレクトリも用意またはテストしてください。

---

30. 最終動作確認

以下を確認してください。

1. /ja/ /en/ でサイドバー表示
2. 日本語と英語のサイドバーが完全分離
3. LanguageSelect 非表示
4. Pagefind が言語別検索
5. index.mdx があるディレクトリ名はリンク
6. リンククリックで一覧ページ表示 + ツリー展開
7. index.mdx はサイドバーに重複表示しない
8. index.mdx がないディレクトリは遷移せずツリー開閉のみ
9. 深いページを直接開いても祖先ツリーが展開
10. DirectoryIndex はリスト表示
11. depth={1,2,3} が期待どおり
12. recursive が全階層
13. Previous / Next 非表示
14. 右 TOC は表示
15. TOC の自動 Overview と本文 ## 概要 が重複しない
16. normalize で title が補完される
17. H1 から title 化しても本文 H1 が維持される
18. normalize 2 回目に diff が出ない
19. section/category の手入力不要
20. Markdown 追加だけでサイドバー・一覧・検索へ反映

---

31. build / check

以下を実行してください。

npm run normalize-content
npm run build

可能であれば:

npx astro check

も実行してください。

また:

npm run normalize-content

を再実行し、冪等性も確認してください。

---

32. 最終報告

作業完了時に以下を報告してください。

1. 追加・変更ファイル
2. 最終ディレクトリ構成
3. 日本語 / 英語 Sidebar 分離方法
4. Sidebar の自動生成ロジック
5. index.mdx 有無によるノード挙動
6. current / ancestor の自動展開方法
7. DirectoryIndex の depth / recursive 実装
8. DirectoryIndex の並び順
9. Pagefind の言語別検索方法
10. LanguageSelect の非表示方法
11. Previous / Next の無効化方法
12. TOC overview 重複の解消方法
13. normalize-content の title 判定ロジック
14. H1 維持と冪等性の実装
15. section/category のパス自動判定方法
16. README 更新内容
17. npm run build / astro check の結果
18. 今後 Markdown を追加する具体的な運用方法

不要なリファクタは避け、将来 Starlight を更新しやすい構成にしてください。