도입: MDX 블로그 Frontmatter 설계의 목표와 한 줄 답
Frontmatter는 글 위에 붙는 메모가 아니라 목록·상세 페이지·사이트맵·검색·공유 이미지에 공통으로 사용되는 콘텐츠 계약이다. 필요한 필드를 작게 시작하고, 스키마로 검증하며, URL처럼 한번 공개하면 바꾸기 어려운 값과 화면용 값을 분리하는 것이 핵심이다. MDX 자체가 YAML frontmatter를 기본 기능으로 해석하는 것은 아니므로 현재 빌드 도구가 어떤 파서를 사용하는지도 먼저 확인해야 한다.
MDX 블로그 Frontmatter 설계와 필드 관리 핵심 항목
1. 소비 지점부터 목록화하기
- 준비: 글 목록, 상세 페이지, RSS, 사이트맵, Open Graph가 어떤 데이터를 읽는지 적는다.
- 단계: 각 화면에서 실제로 사용하는 필드만 모아 필수와 선택으로 나눈다.
- 주의점: 언젠가 쓸 것 같은 필드를 먼저 만들면 빈 값과 예외 처리만 늘어난다.
- 완료 기준: 모든 필드에 최소 한 곳의 소비 코드와 책임이 연결되어 있다.
2. 최소 스키마 정하기
- 준비: 새 글 한 편을 표시하는 데 필요한 최소 정보를 선택한다.
- 단계:
title,description,date,tags,draft,coverImage부터 시작하고 프로젝트 요구에 따라 확장한다. - 주의점: 날짜 문자열 형식과 태그 타입을 글마다 다르게 허용하지 않는다.
- 완료 기준: 새 글 템플릿과 타입 정의가 같은 필드 이름과 타입을 사용한다.
---
title: "R2 이미지 운영 가이드"
description: "R2 공개 주소와 캐시를 점검하는 방법"
date: "2026-09-18"
tags: ["Cloudflare", "R2"]
draft: false
coverImage: "https://assets.example.com/blog/r2-guide/cover.jpg"
---
3. 빌드 전에 검증하기
- 준비: Zod 같은 스키마 검증 도구 또는 자체 검증 함수를 준비한다.
- 단계: 파일을 읽은 직후 타입, 필수값, 날짜, URL, 태그 중복을 검사한다.
- 주의점: 렌더링 중간에 오류를 발견하면 어떤 파일이 원인인지 찾기 어렵다.
- 완료 기준: 잘못된 frontmatter를 가진 파일명이 포함된 명확한 빌드 오류가 나온다.
const Frontmatter = z.object({
title: z.string().min(1),
description: z.string().min(1),
date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/),
tags: z.array(z.string()).default([]),
draft: z.boolean().default(false),
coverImage: z.string().url(),
})
4. slug와 날짜의 역할 분리하기
- 준비: URL을 파일명에서 만들지 별도
slug에서 만들지 결정한다. - 단계: 한번 공개된 URL은 유지하고 제목 변경이 slug를 자동으로 바꾸지 않게 한다.
- 주의점:
date를 수정일처럼 계속 바꾸면 정렬과 사이트맵 의미가 흐려진다. - 완료 기준: 게시일과 수정일 정책, slug 변경 시 redirect 정책이 문서화되어 있다.
5. coverImage를 필수 계약으로 만들기
- 준비: 카드, 본문 상단, Open Graph 중 어디에서 커버를 사용할지 정한다.
- 단계: 공개 글은 유효한 절대 URL을 요구하고, 빌드나 게시 전에 실제 이미지 응답을 확인한다.
- 주의점: 검수용 URL이나 임시 로컬 경로를 최종 frontmatter에 저장하지 않는다.
- 완료 기준: 공개 MDX에는 published 경로만 들어가며 이미지가 없으면 게시 단계가 실패한다.
6. 스키마 변경을 마이그레이션으로 다루기
- 준비: 필드 추가·이름 변경이 기존 글에 미치는 영향을 검색한다.
- 단계: 선택 필드로 추가하고 기존 글을 채운 뒤 필수 필드로 전환한다.
- 주의점: 코드만 먼저 바꾸면 오래된 글이 한꺼번에 빌드를 깨뜨릴 수 있다.
- 완료 기준: 모든 MDX를 순회하는 검증 명령이 통과하고 이전 필드가 남아 있지 않다.
전체 실행 순서
먼저 현재 컴포넌트가 읽는 필드를 조사한다. 최소 스키마와 날짜·URL 정책을 문서화하고 파서 직후 검증을 붙인다. 새 글 템플릿을 스키마에 맞춘 다음 기존 파일 전체를 검사한다. 마지막으로 coverImage의 공개 URL과 slug 충돌을 확인한 뒤 CI에서 같은 검증을 실행한다.
주의점과 실패하기 쉬운 지점
YAML에서 따옴표가 필요한 값, 시간대가 섞인 날짜, 문자열과 배열이 혼용된 tags가 자주 문제를 만든다. MDX는 frontmatter를 자체적으로 지원하지 않으므로 사용 중인 프레임워크·플러그인의 파싱 방식을 확인해야 한다. 설명문을 본문에서 자동 추출할 때는 코드와 제목이 섞이지 않도록 별도 정제 과정이 필요하다.
완료 확인 체크리스트
- [ ] 필수·선택 필드와 타입이 문서화되어 있다.
- [ ] 모든 MDX 파일이 동일한 스키마 검증을 통과한다.
- [ ] date, updatedAt, slug의 의미가 구분되어 있다.
- [ ] 공개 글에는 검증된 coverImage URL이 있다.
- [ ] draft 글은 목록·사이트맵에서 제외된다.
- [ ] slug 충돌과 잘못된 URL을 빌드 전에 발견한다.
- [ ] 스키마 변경 절차와 기존 글 마이그레이션 방법이 있다.
참고 자료
- MDX 공식 가이드, Frontmatter
- Next.js Metadata Files 문서