Communitygithub.com

khaym/stitch-to-astro

Stitch デザインから Astro Content Collections を使用した動的ルーティングによるページ作成手順

stitch-to-astro とは?

このスキルは、Stitch の画面設計情報(docs/stitch/reference.md)とプロジェクト進行メモ(progress.md)を基に、Astro 5 の Content Layer API(Content Collections)を活用したコンテンツ駆動型ページを作成するためのステップバイステップ手順を提供します。スキーマ定義から MDX データ作成、動的ルーティングページの実装、セクションコンポーネントの設計、そしてビルド確認までを網羅しており、特にスキーマ設計は「最小限から始めて段階的に拡張する」ガイドラインを推奨しています。対応プラットフォームは Astro 5 で動作し、画像管理や YAML フロントマターの落とし穴(月名や Yes/No の自動変換)への対処法も含まれています。スキルマークダウンでは CLI コマンドやコードブロックをそのまま保持しつつ、手順全体を日本語でわかりやすく説明しています。

対応~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/khaym/stitch-to-astro/tree/HEAD/.claude/skills/page-procedure

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

コンテンツページ手順

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 が成功する
  • すべてのセクション(モバイル幅を含む)をブラウザで視覚確認済み

関連スキル