마크다운 프론트매터 YAML을 JSON으로 변환하기 — 5개 SSG 호환성과 5가지 함정

Q: 프론트매터에 YAML 대신 JSON을 직접 써도 되나요?

사용 중인 SSG가 지원한다면 가능합니다. Hugo와 Eleventy는 { ... } 형태의 JSON 프론트매터를 기본 지원합니다. 하지만 Astro, Jekyll, Gatsby, Docusaurus 등 다수의 프레임워크는 JSON 프론트매터를 인식하지 못하므로 범용적인 호환성이 필요하다면 YAML 형식을 유지하는 것이 좋습니다.

Q: 옵시디언(Obsidian)의 프론트매터도 JSON으로 변환할 수 있나요?

네, 옵시디언의 프로퍼티(Properties) 및 프론트매터는 표준 YAML 형식을 따르므로 상단 --- 블록을 그대로 복사해 YAML JSON 변환기에 넣으면 정상적으로 JSON 변환이 가능합니다.

Q: 프론트매터 구분선(`---`)을 변환기에 그대로 넣으면 에러가 나나요?

도구에 따라 다릅니다. YAML 사양에서 ---는 유효한 문서 시작 기호이지만, 변환 파서에 따라 최상위 구분선을 파싱하지 못하거나 빈 객체를 반환하는 경우가 있습니다. 안정적인 변환을 위해 구분선 안쪽의 YAML 본문만 복사해 붙여넣는 것을 권장합니다.

마크다운(Markdown) 파일 맨 위에 위치하는 프론트매터(frontmatter, ---로 감싸인 YAML 블록)를 JSON으로 변환해야 하는 상황은 실무에서 자주 발생합니다. 헤드리스 CMS(Contentful, Strapi 등)로 기존 문서를 마이그레이션할 때, 빌드 스크립트에서 메타데이터만 추출해 인덱스를 생성할 때, 다른 정적 사이트 생성기(SSG)로 전환할 때, 혹은 LLM(ChatGPT, Claude)에 구조화된 RAG 컨텍스트를 제공할 때가 대표적입니다.

가장 빠른 방법은 마크다운 파일을 열어 상단 --- 사이의 YAML 본문만 복사한 뒤 YAML JSON 변환기에 붙여넣는 것입니다. FormatArc는 모든 변환 처리가 브라우저 내부에서만 완결되므로 비공개 문서나 사내 위키의 프론트매터도 외부 유출 걱정 없이 안전하게 다룰 수 있습니다.

이 글에서는 마크다운 문서에서 프론트매터만 안전하게 추출해 JSON으로 변환하는 절차와 SSG별 지원 형식 매트릭스, 그리고 변환 시 데이터가 깨지기 쉬운 5가지 YAML 타입의 주의점을 상세히 정리합니다.

결론: 프론트매터는 '구분선 + YAML 본문', 변환 시에는 본문만 전달

일반적인 마크다운 프론트매터는 다음과 같은 3단 구조로 이루어져 있습니다.

---
title: "첫 번째 블로그 포스트"
date: 2026-06-22
tags: ["intro", "demo"]
draft: false
---

여기서부터 실제 마크다운 본문이 시작됩니다.

위아래를 감싸는 ---는 YAML 사양에서 문서 구분선(document separator) 역할을 합니다. 하지만 일반적인 YAML 파서나 온라인 변환기에 넘길 때는 구분선을 제외하고 가운데 4줄의 YAML 본문만 넘기는 것이 가장 안전합니다.

위 예시의 YAML 본문(제목부터 draft까지)을 YAML JSON 변환기에 붙여넣으면 다음과 같은 JSON이 즉시 생성됩니다.

{
  "title": "첫 번째 블로그 포스트",
  "date": "2026-06-22",
  "tags": ["intro", "demo"],
  "draft": false
}

결과 JSON에서 각 필드의 데이터 타입을 확인해 보세요. title과 date는 문자열, tags는 배열, draft는 불리언(boolean) 값으로 정확하게 매핑됩니다. YAML의 암묵적 타입 추론이 올바르게 동작해야만 신뢰할 수 있는 JSON 결과물을 얻을 수 있습니다.

FormatArc YAML to JSON 도구에서 프론트매터를 변환하는 화면

프론트매터를 JSON으로 변환하는 4가지 이유

프론트매터의 JSON 변환 수요는 크게 다음 4가지 실무 시나리오로 나뉩니다. 목적에 따라 변환해야 할 범위와 데이터 검증 포인트가 달라집니다.

1. 헤드리스 CMS 및 REST/GraphQL API 연동

Contentful, Strapi, Sanity, microCMS와 같은 헤드리스 CMS는 글의 메타데이터를 정형화된 JSON 객체로 관리합니다. 로컬 마크다운 파일로 관리하던 블로그 글이나 문서를 CMS로 마이그레이션할 때, 프론트매터를 JSON으로 변환하여 API의 POST 페이로드에 포함하는 것이 일반적인 흐름입니다.

2. 빌드 스크립트에서 메타데이터만 추출

글 전체 목록 JSON, 태그별 게시글 집계, 날짜순 아카이브 인덱스 등을 생성할 때 무거운 마크다운 본문 전체를 파싱할 필요 없이 프론트매터만 JSON으로 파싱하면 빌드 속도를 크게 높일 수 있습니다. Node.js 환경에서는 gray-matter, Python 환경에서는 python-frontmatter 라이브러리를 많이 사용합니다.

3. 정적 사이트 생성기(SSG) 마이그레이션

Jekyll에서 Astro로, 혹은 Hugo에서 Next.js(Contentlayer/MDX)로 블로그 엔진을 교체할 때 기존 프론트매터의 키 이름과 데이터 구조를 점검해야 합니다. 예를 들어 Hugo의 params.foo 구조는 Astro의 Content Collections 스키마와 직접 호환되지 않으므로, JSON 형태로 중간 변환해 필드 구조를 매핑하는 작업이 필요합니다.

워드프레스(WordPress) 등 CMS에서 내보낸 데이터를 마크다운으로 전환하는 경우에는 초기 프론트매터가 없으므로 본문 추출과 함께 제목, 작성일, 슬러그를 조립해 프론트매터를 생성해야 합니다. 자세한 이전 절차는 워드프레스 글을 마크다운으로 옮기는 방법을 참고하세요.

4. LLM 및 RAG 파이프라인 컨텍스트 구조화

마크다운 문서를 ChatGPT, Claude, 또는 벡터 데이터베이스 기반의 RAG(검색 증강 생성) 파이프라인에 입력할 때 메타데이터를 JSON 형태로 본문과 분리해 전달하면 검색 정확도와 답변 품질이 향상됩니다. 카테고리, 태그, 작성일 등의 속성이 정형 데이터로 인식되기 때문입니다.

프론트매터의 3가지 형식: YAML, TOML, JSON

프론트매터가 항상 YAML로만 작성되는 것은 아닙니다. 사용하는 도구와 SSG에 따라 지원하는 형식이 다릅니다.

1. YAML 프론트매터 (가장 널리 사용됨)

---
title: "안녕, 세상"
date: 2026-06-22
---

하이픈 3개(---)로 시작하고 끝납니다. Jekyll, Hugo, Astro, Eleventy, Gatsby, Docusaurus 등 거의 모든 주요 SSG가 기본 지원합니다.

2. TOML 프론트매터 (Hugo / Zola에서 사용)

+++
title = "안녕, 세상"
date = 2026-06-22
+++

더하기 기호 3개(+++)로 감쌉니다. Rust 기반의 Zola는 TOML을 필수로 요구하며, Hugo는 YAML, TOML, JSON을 모두 지원합니다.

3. JSON 프론트매터 (Hugo / Eleventy 지원)

{
  "title": "안녕, 세상",
  "date": "2026-06-22"
}

중괄호 { ... } 자체가 구분선 역할을 겸합니다. Hugo와 Eleventy는 이를 자체적으로 파싱하지만, Astro와 Jekyll은 JSON 프론트매터를 기본적으로 인식하지 못합니다.

SSG별 프론트매터 지원 현황 비교

주요 정적 사이트 생성기 및 마크다운 프레임워크가 기본적으로 어떤 프론트매터 형식을 지원하는지 비교한 표입니다.

SSG / 프레임워크	YAML (`---`)	TOML (`+++`)	JSON (`{...}`)	비고
Hugo	지원	지원	지원	`.org` 파일의 Org Mode(`#+`)도 지원
Jekyll	지원	미지원	미지원	YAML 전용. 빈 글이어도 상단 `---\n---` 필수
Astro	지원	지원	미지원	JSON 프론트매터는 YAML/TOML로 변환 필요
Eleventy (11ty)	지원	플러그인 필요	지원	TOML은 기본 미지원(커스텀 파서 추가)
Next.js + MDX (`@next/mdx`)	플러그인 필요	플러그인 필요	플러그인 필요	`remark-frontmatter` 등 플러그인 설정 필요
Gatsby	지원	미지원	미지원	`gatsby-transformer-remark`가 YAML 전제
VuePress	지원	미지원	미지원	YAML 전용
Zola	미지원	지원	미지원	TOML 필수. YAML→TOML 변환 필요
Docusaurus	지원	미지원	미지원	YAML 전용 (`gray-matter` 기반)

이 표에서 알 수 있는 핵심 전환 포인트는 다음과 같습니다.

Astro, Jekyll, Gatsby, Docusaurus로 이전하는 경우: JSON 프론트매터를 직접 지원하지 않으므로 반드시 YAML로 변환해 입력해야 합니다.
Zola로 이전하는 경우: 기존 Jekyll이나 Hugo의 YAML 프론트매터를 TOML 형식으로 일괄 변환해야 합니다.

Hugo와 Eleventy는 형식 수용도가 높아 기존 YAML/JSON 데이터를 수정 없이 그대로 활용하기에 유리합니다.

마크다운 문서에서 프론트매터 본문만 추출하기

변환 도구에 붙여넣기 전, 마크다운 문서에서 프론트매터 본문만 깔끔하게 분리하는 순서는 다음과 같습니다.

문서의 1행이 공백 없이 정확히 ---로 시작하는지 확인합니다. (앞에 빈 줄이 있으면 파서가 인식하지 못합니다)
2행부터 아래로 내려가며 단독으로 나오는 다음 --- 행을 찾습니다.
두 --- 사이에 있는 내용(구분선 자체는 제외)을 복사합니다.

복사한 YAML 내용을 YAML JSON 변환기에 붙여넣으면 즉시 JSON으로 변환됩니다. FormatArc는 브라우저 내부에서만 실행되므로 API 키, 사내 비공개 문서, 미발행 포스트의 내용이 외부 서버로 전송되지 않습니다.

수백 개 파일의 대량 배치는 CLI 스크립트로 자동화하더라도, 단일 문서의 설정값 검증이나 CMS 등록 전 페이로드 확인에는 브라우저 도구가 훨씬 간편합니다.

자주 발생하는 파싱 오류와 해결법

parse error: bad indentation: 들여쓰기에 탭(Tab) 문자와 공백(Space)이 섞여 있는 경우입니다. 공백(스페이스 2칸)으로 통일하면 해결됩니다.
mapping values are not allowed here: 값에 콜론(:)이 포함되어 있는데 따옴표로 감싸지 않은 경우입니다. title: "10:00 회의록"처럼 큰따옴표로 감싸주어야 합니다.
could not find expected ':': 리스트 항목 - 뒤나 키 : 뒤에 공백을 빠뜨린 경우입니다.

반대 방향: JSON을 다시 YAML 프론트매터로 변환하기

CMS나 데이터베이스에서 가져온 JSON 메타데이터를 다시 마크다운 파일의 프론트매터로 작성해야 하는 역방향 작업도 빈번합니다. 이 경우 JSON YAML 변환기에 JSON 객체를 붙여넣어 YAML을 생성합니다.

생성된 YAML 결과물을 마크다운 문서 상단에 넣고 위아래에 --- 구분선을 붙여주면 올바른 프론트매터가 완성됩니다.

---
{ 여기에 YAML 변환 결과를 붙여넣습니다 }
---

본문 내용...

특히 Astro, Jekyll, Gatsby처럼 JSON 프론트매터를 지원하지 않는 프레임워크로 CMS 데이터를 마이그레이션할 때 필수적인 절차입니다.

YAML to JSON 변환 시 깨지기 쉬운 5가지 타입

YAML과 JSON은 유사해 보이지만 데이터 타입 사양이 완전히 일치하지 않습니다. 프론트매터 변환 시 데이터가 유실되거나 형태가 바뀌기 쉬운 5가지 타입을 점검해야 합니다.

1. 날짜형 (Date)

YAML 1.1 파서는 2026-06-22를 날짜 객체로 자동 해석할 수 있지만, JSON에는 독립된 Date 타입이 존재하지 않아 문자열로 직렬화됩니다. 결과가 "2026-06-22"처럼 큰따옴표로 감싸진 문자열인지 확인하세요. 타임존이 포함된 2026-06-22T10:00:00+09:00 표기는 ISO 8601 문자열로 그대로 유지됩니다.

2. 여러 줄 문자열 (Multiline)

YAML에서 줄바꿈을 유지하는 |(리터럴 블록)이나 줄바꿈을 공백으로 합치는 >(폴디드 블록) 표기는 JSON으로 변환되면 \n 이스케이프 문자가 포함된 단일 문자열로 변환됩니다.

description: |
  첫 번째 줄입니다.
  두 번째 줄입니다.

위 YAML은 변환 시 다음과 같은 JSON이 됩니다.

{
  "description": "첫 번째 줄입니다.\n두 번째 줄입니다.\n"
}

줄바꿈이 의도한 대로 유지되었는지 확인해야 합니다.

3. 앵커와 별칭 (`&` / `*`)

YAML의 앵커(&id)와 별칭(*id)은 동일한 객체나 값을 재사용하는 문법입니다. 하지만 JSON에는 참조 개념이 없으므로, 별칭으로 참조한 값이 모두 개별 객체로 복사(전개)됩니다. 메모리 절약을 위해 작성했던 구조가 JSON에서는 파일 크기 증가로 이어질 수 있습니다.

4. 커스텀 언어 태그 (`!Ruby/Symbol` 등)

Jekyll의 Ruby 심볼이나 PyYAML의 !!python/object: 같은 특정 프로그래밍 언어 종속 태그는 표준 JSON으로 표현할 수 없습니다. 대부분의 변환기는 에러를 발생시키거나 태그를 무시하고 순수 값만 남깁니다.

5. 불리언 오추론과 노르웨이 문제 (Norway Problem)

YAML 1.1 사양에서는 true/false 외에도 yes, no, on, off, y, n을 불리언 값으로 자동 인식합니다. 예를 들어 국가 코드로 country: NO(노르웨이)를 작성하면 JSON 변환 시 country: false로 둔갑하는 유명한 버그("노르웨이 문제")가 발생합니다.

문자열로 유지해야 하는 값은 YAML 작성 시 반드시 "NO"와 같이 따옴표로 감싸야 합니다.

실무 도구 비교: 브라우저 변환 vs CLI·npm 패키지

프론트매터 변환 도구는 각각의 특성에 따라 적합한 환경이 다릅니다.

도구	추천 용도	특징 및 제약
FormatArc YAML JSON 변환기	단일 파일 확인, CMS 페이로드 검증, 보안 민감 데이터	브라우저 전용, 설치 불필요, 외부 전송 없음
gray-matter새 탭에서 열립니다 (npm)	Node.js 빌드 스크립트, Next.js / Astro 파이프라인	YAML/TOML/JSON 전 형식 지원, 본문과 메타데이터 분리 반환
markdown-to-json새 탭에서 열립니다 (npm)	디렉터리 단위 대량 변환, JSON 아카이브 생성	CLI 전용, YAML 프론트매터 중심
python-frontmatter (PyPI)	Python 기반 데이터 분석, Jekyll 스크립트	YAML 기본 지원, TOML/JSON 옵션
GitHub Actions 워크플로	CI 상에서 PR 생성 시 프론트매터 일괄 유효성 검사	자동화에 적합, 사전 스키마 정의 필요

수백 개의 문서를 주기적으로 빌드하는 CI/CD 환경에서는 CLI 라이브러리를, 단발성 마이그레이션 점검이나 외부 유출이 금지된 내부 기밀 문서를 다룰 때는 브라우저 기반 도구를 선택하는 것이 효율적입니다.

실무 활용 패턴

1. Contentful / Strapi 마이그레이션

CMS의 Content Model에 정의된 필드 이름과 프론트매터의 키 이름이 다를 경우, JSON으로 변환한 뒤 매핑 스크립트를 작성하거나 수동으로 키를 맞춰 API로 전송합니다.

2. 노션(Notion) 내보내기 마크다운 처리

노션에서 내보낸 마크다운 파일에는 기본적으로 YAML 프론트매터가 포함되어 있지 않습니다. 노션 페이지 속성을 별도 JSON으로 내보낸 뒤 마크다운 본문과 병합하거나, 필요한 메타데이터를 프론트매터로 구성한 후 CMS로 가져오는 파이프라인을 구축할 수 있습니다.

3. CI 파이프라인에서 JSON Schema 검증

블로그나 기술 문서 저장소에 PR(풀 리퀘스트)이 올라왔을 때, 필수 필드(title, date, tags) 누락이나 날짜 포맷 오류를 방지하기 위해 프론트매터를 JSON으로 변환한 뒤 ajv 등의 라이브러리로 JSON Schema 유효성 검사를 수행하는 방식이 널리 쓰입니다.

다국어 사이트의 프론트매터

단일 언어 블로그라면 title과 date만으로 충분합니다. 같은 글이 여러 언어로 존재하게 되면 프론트매터에 두 가지가 더 필요해집니다. 파일이 어떤 언어로 작성되었는지를 나타내는 필드와, 같은 글의 번역본끼리 연결하는 필드입니다. 후자가 없으면 빌드 스크립트가 hreflang을 자동 생성할 수 없습니다. 이 글에서 다루는 YAML에서 JSON으로의 변환을 추가 이스케이프 없이 통과하는 최소 형태는 다음과 같습니다.

---
title: "Markdown frontmatter: YAML에서 JSON으로"
locale: "ko"
translationKey: "markdown-frontmatter-yaml-json"
date: "2026-06-22"
---

locale과 translationKey는 단순한 문자열이므로 위에서 언급한 깨지기 쉬운 다섯 가지 유형 중 어느 것도 해당하지 않습니다. 위험한 것은 date(「1. 날짜형 (Date)」 참고)와 값 자체가 언어마다 달라지는 필드입니다. 예를 들어 관련 글 slug 목록에서 어떤 언어에는 있는 글이 다른 언어에는 없는 경우가 해당합니다.

자주 빠지는 함정

본문의 수평선(---)과 프론트매터 구분선 충돌: 마크다운 본문에서 수평선을 그릴 때 ---를 사용하면 일부 파서가 프론트매터 종료 구분선으로 오인할 수 있습니다. 본문 수평선은 ***나 ___로 작성하는 것이 안전합니다.
전각 콜론(：) 입력 오류: 한국어나 일본어 입력기를 사용할 때 : 대신 전각 콜론(：)이 입력되면 YAML 파서가 키 구분자로 인식하지 못해 구문 에러가 발생합니다.
0으로 시작하는 식별자(우편번호, 사번 등): code: 01234처럼 작성하면 YAML 파서가 이를 8진수나 정수 1234로 변환할 수 있습니다. 문자열을 유지하려면 "01234"처럼 따옴표를 사용하세요.

자주 묻는 질문

프론트매터에 YAML 대신 JSON을 직접 써도 되나요?

사용 중인 SSG가 지원한다면 가능합니다. Hugo와 Eleventy는 { ... } 형태의 JSON 프론트매터를 기본 지원합니다. 하지만 Astro, Jekyll, Gatsby, Docusaurus 등 다수의 프레임워크는 JSON 프론트매터를 인식하지 못하므로 범용적인 호환성이 필요하다면 YAML 형식을 유지하는 것이 좋습니다.

옵시디언(Obsidian)의 프론트매터도 JSON으로 변환할 수 있나요?

네, 옵시디언의 프로퍼티(Properties) 및 프론트매터는 표준 YAML 형식을 따르므로 상단 --- 블록을 그대로 복사해 YAML JSON 변환기에 넣으면 정상적으로 JSON 변환이 가능합니다.

프론트매터 구분선(`---`)을 변환기에 그대로 넣으면 에러가 나나요?

도구에 따라 다릅니다. YAML 사양에서 ---는 유효한 문서 시작 기호이지만, 변환 파서에 따라 최상위 구분선을 파싱하지 못하거나 빈 객체를 반환하는 경우가 있습니다. 안정적인 변환을 위해 구분선 안쪽의 YAML 본문만 복사해 붙여넣는 것을 권장합니다.

FormatArc에서 변환할 때 데이터 유출 위험은 없나요?

FormatArc의 모든 데이터 변환 처리는 사용자의 웹 브라우저 안에서 JavaScript로 직접 실행됩니다. 입력한 데이터나 변환 결과가 외부 서버로 업로드되거나 전송되지 않으므로 사내 기밀 설정 파일이나 비공개 글도 안전하게 변환할 수 있습니다.

정리 — 프론트매터 변환 4단계 요약

마크다운 프론트매터의 YAML을 JSON으로 변환하는 절차는 다음과 같습니다.

마크다운 파일에서 --- 사이의 YAML 본문만 복사합니다.
YAML JSON 변환기에 붙여넣어 브라우저에서 즉시 변환합니다.
생성된 JSON에서 날짜, 여러 줄 문자열, 불리언 타입의 정상 변환 여부를 확인합니다.
완성된 JSON을 헤드리스 CMS, 빌드 스크립트, 또는 RAG 파이프라인에 전달합니다.

JSON을 다시 마크다운 프론트매터로 되돌려야 한다면 JSON YAML 변환기를, 마크다운 본문을 HTML로 렌더링하고 싶다면 Markdown to HTML 변환기를 함께 활용해 보세요.

프론트매터의 기본이 되는 YAML 문법이나 JSON과의 차이점에 대해서는 관련 글도 함께 참고해 보세요.

YAML 문법 가이드 — YAML 기본 문법과 작성법
YAML JSON 변환 가이드 — 프론트매터 외 일반적인 YAML→JSON 변환
YAML과 JSON의 차이점 — 두 형식의 비교와 선택 기준
YAML이란? — YAML 기초와 입문
마크다운 HTML 변환 가이드 — 마크다운 본문 변환 방법
CommonMark와 GFM의 차이점 — 마크다운 사양과 확장 문법