숏컷 코드

---
title: 문서 제목
description: 짧은 설명
tags:
  - markdown
  - docs
published: true
---

기본 구조

frontmatter는 Markdown 본문이 아니라 문서 메타데이터다

frontmatter는 Markdown 파일 맨 위에 --- 구분자로 감싼 메타데이터 블록입니다. 제목, 설명, 태그, 날짜, draft 여부처럼 렌더링 시스템이 문서를 분류하거나 페이지 정보를 만들 때 쓰는 값을 둡니다. 일반 Markdown 표준 자체의 문법은 아니며, Jekyll, Hugo, Astro, MDX 기반 사이트처럼 정적 사이트 생성기나 콘텐츠 파이프라인이 관례적으로 해석합니다.

---
title: 설치 가이드
draft: false
---

# 설치 가이드

렌더러가 frontmatter를 지원하지 않으면 --- 블록이 그대로 본문으로 보이거나 수평선으로 처리될 수 있습니다. 따라서 frontmatter를 쓰는 문서는 "어떤 도구가 이 메타데이터를 읽는가"까지 함께 확인해야 합니다.

YAML 문법을 따르므로 들여쓰기와 따옴표가 중요하다

가장 흔한 frontmatter 형식은 YAML입니다. key와 value는 key: value 형태로 쓰고, 배열은 들여쓰기한 - item 형태로 씁니다. :가 포함된 문자열, #이 들어간 문자열, 날짜처럼 자동 타입 변환이 일어날 수 있는 값은 따옴표로 감싸는 편이 안전합니다.

---
title: "API: 인증 흐름"
date: "2026-05-23"
tags:
  - api
  - auth
---

들여쓰기가 어긋나면 문서 본문은 멀쩡해도 빌드나 콘텐츠 검수 단계에서 실패합니다. Markdown 본문 오류처럼 눈에 바로 보이지 않기 때문에 frontmatter는 formatter나 content audit로 함께 검증하는 편이 좋습니다.

첫 줄 위치가 중요하다

대부분의 도구는 파일 첫 줄의 ---를 frontmatter 시작으로 봅니다. 앞에 빈 줄, BOM, 주석, HTML comment가 있으면 frontmatter로 인식하지 못할 수 있습니다. 문서 템플릿을 만들 때는 파일 시작부터 바로 구분자를 두는 방식으로 고정하는 것이 안전합니다.

---
title: 올바른 위치
---

본문이 여기서 시작됩니다.

MDX에서는 frontmatter와 JSX가 함께 쓰일 수 있지만, frontmatter 안에는 JSX를 넣지 않습니다. 동적인 값은 본문 컴포넌트나 빌드 단계 데이터로 넘기고, frontmatter에는 직렬화 가능한 값만 둡니다.

선택 기준

주의할 점

frontmatter의 key 이름은 프로젝트 규칙을 따라야 합니다. 같은 의미에 summary, description, excerpt를 섞어 쓰면 검색, 목록, SEO 생성 로직이 일부 문서를 놓칠 수 있습니다.