콘텐츠 페이지 절차
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가 성공함 - 모든 섹션 (모바일 너비 포함)이 브라우저에서 시각적으로 확인됨