コンテンツページ手順
Astro Content Collections(Content Layer API)と動的ルーティングを使用したコンテンツ駆動ページを作成するためのステップバイステップ手順です。
前提条件
src/styles/global.cssがデザイントークンと共に存在すること(css-procedure により作成済み)docs/stitch/reference.mdが存在すること(Stitch 画面からのフィールド情報)
入力 / 出力
[入力] [出力]
docs/stitch/reference.md ──┐
(画面フィールド情報) │
progress.md ノート ──────────┼──→ src/content/config.ts (スキーマ)
(セクション構造、 │ src/content/<collection>/<slug>/index.mdx (データ)
デザイン決定事項) │ src/pages/<collection>/[...slug].astro (ルーティング)
│ src/components/*.astro (セクションコンポーネント)
手順
ステップ 1: スキーマ定義 (src/content/config.ts)
Astro 5 Content Layer API は glob ローダーを使用します。
1-1. コレクションの定義
import { defineCollection, z } from "astro:content";
import { glob } from "astro/loaders";
const myCollection = defineCollection({
loader: glob({ pattern: "**/index.mdx", base: "./src/content/my-collection" }),
schema: ({ image }) =>
z.object({
title: z.string(),
// ... フィールドを定義
heroImage: image(), // 画像には image() ヘルパーを使用
}),
});
export const collections = { myCollection };
1-2. スキーマ設計ガイドライン
- 最小限から始め、段階的に拡張する。 現在のページレンダリングに必要なフィールドのみ定義し、コンポーネント実装時に追加する
- 画像フィールドには
image()ヘルパーを使用し、ビルド時のパス検証と最適化を有効にする - すべてのエントリーで必須でないフィールドには
.optional()を使用する - セクションレベルのデータにはオプショナル配列を使用し、ページごとのセクション表示を制御する:
// スキーマ moments: z.array(z.object({ title: z.string(), ... })).optional()<!-- ページテンプレート: 条件付きレンダリング --> {data.moments && <MomentsSection moments={data.moments} />}
1-3. YAML フロントマターの落とし穴
- 月名(March, May など)や Yes/No は YAML によって自動変換されます。 文字列として扱いたい場合は引用符で囲む:
date: "March" - 画像パスは MDX ファイルからの相対パス:
heroImage: ./hero.jpg
ステップ 2: コンテンツデータの作成
2-1. ディレクトリ構造
src/content/<collection>/<slug>/
├── index.mdx # フロントマター + MDX 本文
├── hero.jpg # 画像はコンテンツと一緒に配置
└── ...
2-2. MDX ファイル構造
---
title: "ページタイトル"
heroImage: ./hero.jpg
description: "説明テキスト"
---
## MDX 本文
本文コンテンツは `render()` で取得し、`<Content />` としてレンダリングします。
2-3. 画像管理
- 画像は
src/content/内に、コンテンツと一緒に配置する(public/ではない) - 画像はコミット前に 2560px を超える場合はリサイズする
- スキーマで
image()ヘルパーを使用すると、フロントマターの画像パスはImageMetadata型に解決される。コンポーネントの Props でもImageMetadataを使用する
ステップ 3: 動的ルーティングページ
src/pages/<collection>/[...slug].astro を作成:
---
import type { GetStaticPaths } from "astro";
import { getCollection, render } from "astro:content";
export const getStaticPaths = (async () => {
const items = await getCollection("myCollection");
return items.map((item) => ({
params: { slug: item.id },
props: { item },
}));
}) satisfies GetStaticPaths;
const { item } = Astro.props;
const { Content } = await render(item);
---
重要なポイント
getCollection()ですべてのエントリーを取得;getStaticPathsで静的パスを生成render()は MDX 本文をContentコンポーネントとして返すitem.dataでフロントマターフィールドに型安全にアクセス- オプショナルフィールドの条件付きレンダリング:
{data.field && <Component ... />}
ステップ 4: ページデータファイル (src/data/<page>.md)
各ページのユーザー編集可能なコンテンツ(テキスト、ラベル、URL)は、src/data/ 以下に YAML フロントマター付きの Markdown ファイルで定義します。これにより Content Collections と形式が統一され、ユーザーがコンテンツを見つけて編集しやすくなります。
注:
src/data/ディレクトリはスキャフォールドスキルでは作成されません。このステップで作成してください。
4-1. ページごとにデータファイルを作成
src/data/
├── index.md # 作品(トップ)ページコンテンツ
├── about.md # About Me ページコンテンツ
└── skills.md # スキルページコンテンツ
4-2. 編集可能なコンテンツを YAML フロントマターとして定義
---
# ==============================
# 作品ページコンテンツ
# このファイルを編集してページをカスタマイズしてください。
# ==============================
hero:
headingPrefix: "こんにちは、私は"
highlightedText: "Web デベロッパーです。"
description: "スケーラブルでユーザー中心のアプリケーションを構築しています..."
badgeText: "新しいプロジェクト募集中"
cta:
heading: "一緒に何か作りませんか?"
description: "現在フリーランスの機会を探しています..."
buttons:
- label: "お問い合わせ"
href: "mailto:[email protected]"
variant: "primary"
- label: "CV をダウンロード"
href: "#"
variant: "secondary"
---
- YAML にはユーザーが編集可能なテキストのみ(文字列、ラベル、URL、テキストの配列)を記述する
- 編集不可能なデータ(SVG アイコンパスなど)は、
.astroページファイル内の TypeScript 定数として保持する
4-3. ページ内でデータをインポート
import.meta.glob() を使用してフロントマターを読み込む:
---
const content = Object.values(
import.meta.glob("../data/index.md", { eager: true })
)[0] as { frontmatter: Record<string, unknown> };
const { hero, cta } = content.frontmatter;
---
ステップ 5: セクションコンポーネントの実装
各セクション(hero, moments など)は src/components/ に独立したコンポーネントとして作成します。コンポーネント構造と CSS ルールについては develop-guideline に従ってください。
画像表示: <Picture> vs <img>
| 方法 | 使用する場合 | 例 |
|---|---|---|
<Picture> | ビルド時に既知の静的画像 | ヒーロー背景、エントリー画像 |
<img> | クライアント JS で動的に差し替える画像 | モーダルギャラリースライドショー |
<Picture> はビルド時にレンダリングされるため、クライアント JS で src が差し替えられる場合は使用できません。
クライアントサイド JavaScript
Astro コンポーネント内の <script> タグはクライアント JS として実行されます。フレームワーク(React など)を使わずにインタラクティブ機能を構築できます。
データ受け渡しパターン: data-* 属性を使用してフロントマターデータをクライアント JS に渡します。<script> はフロントマター変数を直接参照できません。
アクセシビリティ: モーダル / オーバーレイ
モーダルダイアログ実装のチェックリスト:
| 要件 | 実装 |
|---|---|
| セマンティクス | role="dialog" + aria-modal="true" + aria-label |
| 開閉 | hidden 属性の切り替え + CSS opacity トランジション |
| スクロールロック | 開く: document.body.style.overflow = "hidden" / 閉じる: "" に戻す |
| キーボード | Escape で閉じる、矢印キーでナビゲーション |
| フォーカストラップ | Tab/Shift+Tab でモーダル内のボタンを循環 |
| フォーカス復元 | 閉じるときにトリガー要素に focus() |
| バックドロップで閉じる | クリック対象がインタラクティブ要素でない場合に閉じる |
| z-index | 既存の固定要素よりも高い値(例: ヘッダー 50 → モーダル 60) |
ステップ 6: ビルド確認
npm run build
Content Collections のスキーマ検証エラーはビルド時に明確なメッセージとともに表示されます。
よくあるエラー
| エラー | 原因 | 修正 |
|---|---|---|
Expected type "string", received "object" | YAML が値を自動変換した(月名→Date など) | 値を引用符で囲む |
Could not find image | 画像パスが正しくない | MDX ファイルからの相対パスを確認 |
does not match collection schema | フロントマターにフィールドがない、または型が一致しない | config.ts のスキーマと照合 |
ステップ 7: 開発サーバー確認
npm run dev
- スキーマ変更後は開発サーバーの再起動が必要な場合があります(コンテンツストアのクリア)
- 再起動後もエラーが続く場合は
.astro/ディレクトリを削除して再起動
チェックリスト
-
src/content/config.tsにスキーマが定義されている - MDX フロントマターがスキーマに準拠している
- 画像が
src/content/内にあり、2560px 以下にリサイズされている -
[...slug].astroがgetStaticPathsですべてのエントリーを返している - オプショナルフィールドのセクションが条件付きレンダリングを使用している
-
npm run buildが成功する - すべてのセクション(モバイル幅を含む)をブラウザで視覚確認済み