Astro 콘텐츠 컬렉션 - 글 쓸 때 자동 처리되는 것들¶

한 줄 요약: .md 파일의 frontmatter(앞에 있는 메타데이터)는 페이지 템플릿이 자동으로 읽어서 쓴다. 어떤 필드가 어디에 자동 노출되는지 알아두면 본문에 같은 사진/제목을 두 번 쓰는 함정을 막는다.

콘텐츠 컬렉션이 뭐야¶

Astro 사이트(예: storywinner)에서 글, 강의 후기, 책 소개 같은 걸 .md 파일로 관리하는 시스템. 폴더 구조:

src/content/
├── lectures/          ← 강의 후기 컬렉션
│   ├── 강의1.md
│   └── 강의2.md
├── content/           ← 블로그 글 컬렉션
└── books/             ← 책 소개 컬렉션

각 .md 파일 맨 위에 ---로 감싼 부분이 frontmatter:

---
title: "공공기관 AI 바이브 코딩 강의"
photos: ["사진1.jpg", "사진2.jpg", "사진3.jpg"]
date: "2026-04-08"
---

본문 내용...

자동으로 노출되는 필드들 (storywinner 기준)¶

페이지 템플릿(src/pages/lectures/[...slug].astro 등)이 frontmatter를 자동으로 읽어서 쓴다.

필드	자동 노출되는 곳	본문에 또 쓰면?
title	페이지 H1, 브라우저 탭 제목, OG 태그	H1 중복 → SEO 감점
photos[0]	페이지 상단 hero 이미지 (큰 사진)	같은 사진 두 번 노출됨
date	본문 위 날짜 표시	중복
org / topics / target	메타 정보 박스	중복
feedback	후기 인용 박스	중복

"본문 마크다운에 또 쓰면 두 번 보인다"가 핵심.

비유로 이해¶

frontmatter = 이력서 양식의 빈 칸들. - 이름 칸에 적은 걸 회사가 자동으로 명함, 명패, 사원증에 인쇄해줌 - 그런데 자기소개서 본문에 또 "제 이름은 ○○○입니다"라고 쓰면 중복

2026-05-10 사고 - photos[0] hero 함정¶

건보 1일차 후기에 입구 사진을 추가하면서: 1. photos 배열 첫 번째에 입구 사진 추가 (의도: 페이지 hero용) 2. 본문 마크다운에도 입구 사진을 또 넣음 (실수)

→ 페이지 상단에 입구 사진이 두 번 연속 보였음.

해결: 본문에서 입구 사진 제거. hero(photos[0])에서만 보이게.

강의 후기 작성 규칙 (storywinner)¶

photos 배열은 갤러리 + hero용으로만 생각
photos[0] = 페이지 상단 큰 사진 (hero)
photos[1~] = 페이지 하단 갤러리에 들어감
본문 마크다운에 넣는 이미지는 photos에 있는 거 또 쓰지 말고, 본문 흐름 설명용으로 따로 골라서 넣기
또는 photos에 안 넣고 본문에서만 쓰기
새 글 쓰기 전에 페이지 템플릿(src/pages/<컬렉션>/[...slug].astro) 한 번 훑어보기
lecture.data.photos[0]처럼 frontmatter 어떤 필드를 어떻게 쓰는지 확인

비슷한 패턴 (다른 사이트도)¶

이 패턴은 Astro만의 일이 아님. 정적 사이트 생성기(11ty, Hugo, Jekyll 등)는 다 비슷: - 11ty: data.front_matter 사용 - Hugo: params 사용 - Next.js: getStaticProps로 frontmatter 읽음

frontmatter에 적은 건 "메타데이터" 영역, 본문 마크다운은 "콘텐츠" 영역. 둘이 다른 곳에 노출된다는 점만 머리에 박아두면 됨.

실전 디버깅¶

"왜 이 글에 같은 사진이 두 번 나오지?" 싶으면:

# 페이지 HTML에서 같은 이미지 URL이 몇 번 나오는지
$html = (Invoke-WebRequest -Uri "사이트URL").Content
[regex]::Matches($html, '의심되는파일명').Count

2 이상 나오면 중복. frontmatter 또는 본문 둘 중 하나에서 빼면 됨.

마크다운 강조(`**`) 깨짐 - 한국 punctuation 인접 함정 (storywinner 5/12 학습, CLAUDE.md에서 이동)¶

원인: CommonMark/remark는 ** 양쪽이 한국 punctuation(『』, 「」, 따옴표, 괄호)으로 둘러싸이면 left/right-flanking 조건을 못 채워 강조 처리 실패. **가 그대로 본문에 노출됨.

깨지는 패턴 → 안전한 패턴 - **『친절한 말하기』** → 『**친절한 말하기**』 (따옴표 밖, 강조 안) - **"인용 문장"** → "**인용 문장**" - **'단어'** → '**단어**' - **과객 - "글 제목"** → **과객** - "**글 제목**" (한 line 내 여러 강조로 분리)

규칙: ** 바로 옆에 한국 따옴표/괄호가 오지 않게. 따옴표/괄호는 강조 밖, 강조는 안쪽 텍스트에만. 영문 따옴표도 동일.

검증: Grep 패턴 \*\*[『「“‘\(\[]|[』」”’\)\]]\*\* 으로 콘텐츠 폴더 검색