Communitygithub.com

khaym/stitch-to-astro

Stitch 디자인에서 Astro Content Collections와 동적 라우팅을 사용하여 페이지를 생성하는 절차

stitch-to-astro란 무엇인가요?

이 스킬은 디자인 참조(Stitch)에서 추출한 필드 정보를 기반으로 Astro Content Collections를 활용한 콘텐츠 중심 페이지를 생성하는 단계별 절차를 제공합니다. 개발자는 docs/stitch/reference.md 파일의 화면 필드 정보와 progress.md 노트를 입력으로 받아, src/content/config.ts에 스키마를 정의하고, 실제 콘텐츠 데이터를 MDX 파일로 작성하며, [...slug].astro 동적 라우트를 구성하게 됩니다. 또한 선택적 섹션 컴포넌트 구현, YAML 프론트매터 주의사항, 이미지 관리, 페이지별 데이터 파일(src/data/) 관리, 접근성 가이드라인을 포함하여 완전한 페이지 개발 워크플로를 제공합니다. Astro 5의 Content Layer API와 glob 로더를 사용하며, 빌드 타임 스키마 검증과 정적 사이트 생성을 지원합니다. Cursor, Windsurf 등 Astro 프로젝트를 다루는 모든 AI 코딩 에이전트에 적합합니다.

지원 대상~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. 이미지 관리

  • 이미지는 public/이 아닌 src/content/ 내에 콘텐츠와 함께 저장하세요.
  • 커밋하기 전에 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      # 작업(Works) 페이지 콘텐츠
├── about.md      # 소개(About Me) 페이지 콘텐츠
└── skills.md     # 기술(Skills) 페이지 콘텐츠

4-2. YAML 프론트매터로 편집 가능한 콘텐츠 정의

---
# ==============================
# 작업 페이지 콘텐츠
# 이 파일을 편집하여 페이지를 사용자 정의하세요.
# ==============================

hero:
  headingPrefix: "안녕하세요, 저는"
  highlightedText: "웹 개발자입니다."
  description: "확장 가능하고 사용자 중심의 애플리케이션을 구축합니다..."
  badgeText: "새 프로젝트 가능"

cta:
  heading: "함께 무언가를 만들어볼 준비가 되셨나요?"
  description: "현재 프리랜스 기회에 열려 있습니다..."
  buttons:
    - label: "연락하기"
      href: "mailto:[email protected]"
      variant: "primary"
    - label: "이력서 다운로드"
      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>는 빌드 타임에 렌더링되므로 src가 클라이언트 JS에 의해 교체될 때 사용할 수 없습니다.

클라이언트 측 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가 성공함
  • 모든 섹션 (모바일 너비 포함)이 브라우저에서 시각적으로 확인됨

관련 스킬