Front matter — 파일 맨 위 YAML/TOML/JSON · Markup Quest

본문 위의 메타데이터 블록

Front matter 는 Markdown 파일 맨 위에 얹는 구조화된 데이터 블록이야. 제목, 날짜, 태그, draft 여부 같은 걸 담아. 정적 사이트 생성기 (Hugo, Jekyll, Astro, Next MDX, Eleventy) 가 이걸 읽고 라우팅과 정렬, 인덱싱, 렌더링을 정해. 그 아래부터는 그냥 평범한 Markdown 이고.

세 flavor

YAML — --- 로 감싸. 제일 많이 쓰여. Jekyll, Hugo, Astro, Next MDX, Pelican, Gatsby 가 다 이 방식이야.
TOML — +++ 로 감싸. Hugo 가 좋아하는 방식이지. 따옴표를 꼭 쓰고 규칙이 분명해서 더 잘 읽혀.
JSON — 보통 ;;; 로 감싸거나 { ... } 블록으로 써. 훨씬 덜 쓰이고, 일부 MDX 셋업만 기본으로 받아줘.

흔한 키 (관행이지 spec 은 아냐)

title, date, slug, tags, categories, draft, author, cover 정도가 기본이야. 여기에 생성기마다 자기 키를 더 얹어. Hugo 의 weight, Jekyll 의 layout 과 permalink 같은 것들. 정확한 목록은 그 생성기 문서를 봐야 해.

YAML front matter 의 Norway 문제: YAML 1.1 에서 tags: [no, yes, on, off] 는 [false, true, true, false] 로 파싱돼. 키워드처럼 생긴 문자열 값은 무조건 따옴표로 감싸. tags: ["no", "yes"] 이렇게. YAML 트랙에서 제대로 파고들 거야.

Code

YAML front matter (가장 흔함)·markdown

---
title: "My First Post"
date: 2026-05-04
tags: [markdown, intro, gfm]
draft: false
---

# My First Post

The body of the document is normal Markdown.

TOML front matter (Hugo flavor)·markdown

+++
title = "My First Post"
date = 2026-05-04
tags = ["markdown", "intro", "gfm"]
draft = false
+++

# My First Post

The body of the document is normal Markdown.

JSON front matter (일부 MDX)·markdown

;;;
{
  "title": "My First Post",
  "date": "2026-05-04",
  "tags": ["markdown", "intro", "gfm"],
  "draft": false
}
;;;

# My First Post

Exercise

프로젝트의 Markdown 파일을 하나 골라 (README 든 일지든 블로그 초안이든). 거기에 front matter 를 YAML, TOML, JSON 세 가지로 각각 써봐. 같은 생성기로 (Hugo 나 Astro) 렌더링해서 결과를 비교하고. 그 다음 앞으로 commit 할 하나를 고르고, 왜 그걸 골랐는지 적어둬.

Front matter — 파일 맨 위 YAML/TOML/JSON

본문 위의 메타데이터 블록

세 flavor

흔한 키 (관행이지 spec 은 아냐)

Code

External links

Exercise

Progress

댓글 0