Astro を使う理由

前回の前提——ナレッジベース型・一覧/詳細/タグ・コンテンツ2系統・静的サイト——は Astro と相性がいい です

規模が小さく、DB や認証も要らない。長文は Content Collections、短文のあるあるは JSON で分けられる。このブログ（hack-plus）は Next.js だが、あるあるサイトは静的中心で足りる ので Astro に決定しました

Astro は初めて なので、まず動くところまで を優先
設計の芯だけ本文に書き、実装の細部はリポの web/ を見る 形（Cursor と一緒に作る）

Astro って何をするフレームワークか

静的サイト向けのフレームワーク
HTML を中心に組み立ててビルド時に出力する——前回で決めた「DB なし・投稿フォームなし」と相性がいい

押さえる用語は3つ
※Islands（インタラクティブ部分だけ JS を載せる思想）は今回は未使用で、一覧・詳細・タグは静的 HTML 中心で足りそう

用語	ざっくり意味	このサイトでの例
`.astro` ファイル	HTML に近いテンプレート。先頭の `---` でデータ取得	トップ、あるある詳細、タグ一覧
Content Collections	Markdown などを型付きで管理	検証記事（長文）
ファイルベースルーティング	`src/pages/` のパスがそのまま URL	`/aruaru`、`/verify`、`/tags/...`

参考: Astro 公式ドキュメント

前回の4条件への当てはめ——ナレッジベース型は pages/ とデータ取得で組める、一覧・詳細・タグは [slug].astro / [tag].astro の定番パターン、2系統は後述、静的サイトは astro build で HTML を吐いて次回ホスティング

コンテンツ2系統の載せ方

あるある（短文・構造化）と検証記事（長文・Markdown）を 別の入れ物 にしました。Cursor に「2系統あるから分けて」と伝えたら、だいたい次の形で起こしてくれました

系統	置き場所	読み込み方	向いている理由
あるある	`src/data/entries.json`	`lib/entries.ts` で Zod 検証	症状・原因・対処のフィールドが固定。短文で件数が増える
検証記事	`src/content/verifications/*.md`	Content Collections	本文が長い。Markdown のまま書きたい

全部 Markdown に統一しなくてよさそう — あるあるは JSON、検証記事は Content Collections、という分担
型定義（content.config.ts や Zod）は Cursor が書いてくれたので、ここでは細部を載せません。実物はリポの web/src/ を見てください

トップでは両方の新着を並べる——という要件を Cursor に渡すと、index.astro の frontmatter（--- ブロック）で getEntries() と getCollection('verifications') を呼ぶ形になりました

ページの作り方（ルーティング）

URL は src/pages/ のファイル名がそのまま対応します

src/pages/
├── index.astro              → /
├── aruaru/
│   ├── index.astro          → /aruaru（一覧）
│   └── [slug].astro         → /aruaru/{slug}（詳細）
├── verify/
│   ├── index.astro
│   └── [slug].astro
└── tags/
    └── [tag].astro          → /tags/{tag}

あるある詳細は [slug].astro + getStaticPaths の定番パターン。JSON にエントリを足すとビルド時に詳細ページが増える——CMS なしでも回る形です
getStaticPaths の書き方は web/src/pages/aruaru/[slug].astro を参照

スタイルは Tailwind CSS v4（@tailwindcss/vite）を入れています。見た目はまだ仮

雛形を作って、手元で動かす

次は プロジェクトの雛形。開発環境を整えた回の docs/ と web/ の分離 はそのまま、web/ の中身を Astro にしました

Cursor に「前回決めたページ構成で Astro の雛形を」と渡したら、だいたい次のツリーができました。細部はリポを見てください

プロジェクトルート/
├── docker-compose.yml
├── docs/                    … 運用メモ・検証ログ（サイト本体とは分離）
└── web/
    ├── Dockerfile.dev
    ├── astro.config.mjs
    ├── src/
    │   ├── content.config.ts … Content Collections 定義
    │   ├── data/             … あるある（entries.json）
    │   ├── content/          … 検証記事（Markdown）
    │   ├── lib/                … JSON 読み込み・Zod
    │   ├── pages/              … ルーティング
    │   ├── components/
    │   └── layouts/
    └── package.json

前回で決めたページ（一覧・詳細・タグ）が、ここに落ちてくる想定です
URL の細かい名前や見た目はまだ詰めなくてよい——骨組みが動くか だけ見ました

ローカルは docker-compose で起動

いつもどおり docker-compose で揃えます。手元の Node バージョン差を気にしなくてよいのが楽

docker compose up --build

別ターミナルでコンテナが立っているか確認

docker compose ps

web サービスが Up になっていればOK

ブラウザで確認

開発サーバーが立ったら、ブラウザでトップページを開きます
一覧がざっくり出ていれば、今回のゴールはクリアです

手元で表示できたトップページ

デザインの細部はまだ仮、動いたことだけ 先に確認

今回の HACK+PLUS

前回の前提を Astro で実装し、二系統コンテンツの載せ方と手元起動までのメモです

HACK（新しい発見）

Astroは、あるあるを JSON、検証記事を Content Collections と 二系統で載せられる（全部 Markdown にしなくてよさそう）

PLUS（ハマりどころ・次の一手）

コードの正本は リポの web/ — 記事に全部載せるより、手元の clone を見る方が早い
ローカル起動は compose で揃える——開発環境を整えた回のリポ構成の延長