YAML frontmatter

YAML frontmatter는 Markdown 파일 상단에 메타데이터를 정의하는 블록입니다. 파일의 맨 처음에 위치하며, 삼중 대시(---)로 감싸진 YAML 형식으로 작성됩니다. Jekyll을 비롯한 정적 사이트 생성기에서 파일을 특별하게 처리하도록 지시하는 역할을 합니다.

해당 개념이 필요한 이유

• 메타데이터 분리: 콘텐츠와 메타데이터를 명확히 구분
• 템플릿 지원: 레이아웃, 템플릿에서 변수로 접근 가능
• 자동화: 정적 사이트 생성기가 메타데이터를 기반으로 파일 처리
• 구조화: 날짜, 카테고리, 태그 등을 체계적으로 관리

AS-IS

메타데이터를 본문에 포함하거나 파일명으로만 관리해야 합니다.

# My Blog Post
Date: 2025-12-21
Category: web-development
Tags: jekyll, yaml
 
본문 내용...

TO-BE

Frontmatter로 메타데이터를 구조화하여 관리합니다.

---
date: 2025-12-21
category: web-development
tags: [jekyll, yaml]
---
 
# My Blog Post
 
본문 내용...

기본 문법

구조

Frontmatter는 파일의 맨 처음에 위치해야 하며, 삼중 대시(---)로 시작과 끝을 표시합니다.

---
key: value
---
 
본문 내용

주의:

• 파일의 첫 줄부터 시작해야 함
• 빈 줄이나 공백이 앞에 있으면 안 됨
• YAML 문법을 따라야 함

지원되는 데이터 타입

타입	예시	설명
문자열	title: "My Title"	따옴표는 선택사항 (특수문자 포함 시 필수)
숫자	count: 42	정수 또는 실수
불린	published: true	true/false
날짜	date: 2025-12-21	ISO 8601 형식
리스트	tags: [foo, bar]	배열 형태
리스트 (여러 줄)	tags: - foo - bar	YAML 리스트 문법
객체	author: name: John email: john@example.com	중첩 구조

예시

기본 예시:

---
title: Blogging Like a Hacker
layout: post
date: 2025-12-21
---
 
본문 내용

리스트 사용:

---
categories: [web-development, tutorial]
tags:
  - jekyll
  - yaml
  - markdown
---

중첩 객체:

---
author:
  name: John Doe
  email: john@example.com
  github: johndoe
---

커스텀 변수:

---
food: Pizza
drink: Coffee
favorite_number: 42
---
 
<h1>My favorite food is {{ page.food }}</h1>

실제 사용 예시

Claude Code - Project Rules

Claude Code의 .claude/rules/*.md 파일에서 path-specific rules를 정의할 때 frontmatter를 사용합니다.

---
paths:
  - "src/**/*.ts"
  - "lib/**/*.ts"
  - "tests/**/*.test.ts"
---
 
# TypeScript Rules
- Use strict type checking
- No implicit any

여러 경로 패턴:

---
paths:
  - "src/**/*.{ts,tsx}"
  - "{src,lib}/**/*.test.ts"
---
 
# Testing Rules
- All test files must use Jest
- Use descriptive test names

Obsidian 노트

---
aliases: [alias1, alias2]
tags: [note, personal]
created: 2025-12-21
updated: 2025-12-21
---
 
# 노트 제목
 
노트 내용...

주의사항

YAML 문법 준수

# ❌ 잘못된 예시
---
title: My Title: With Colon  # 콜론이 포함된 경우 따옴표 필요
---
 
# ✅ 올바른 예시
---
title: "My Title: With Colon"
---

들여쓰기

# ❌ 잘못된 예시 (탭 사용)
---
author:
	name: John
---
 
# ✅ 올바른 예시 (스페이스 2개)
---
author:
  name: John
---

빈 frontmatter

일부 시스템에서는 빈 frontmatter로도 특별 처리를 활성화할 수 있습니다.

---
---
 
본문 내용

Best Practices

기본값 설정

자주 사용하는 frontmatter 변수는 기본값으로 정의하여 중복을 줄입니다.

Jekyll _config.yml:

defaults:
  - scope:
      path: "_posts"
      type: posts
    values:
      layout: post
      author: default_author

명확한 키 이름

# ✅ 좋은 예시
---
publication_date: 2025-12-21
author_name: John Doe
---
 
# ❌ 나쁜 예시
---
pd: 2025-12-21
an: John Doe
---

일관된 데이터 타입

# ✅ 좋은 예시 (일관된 리스트)
---
tags: [foo, bar, baz]
---
 
# ❌ 나쁜 예시 (혼재)
---
tags: foo, bar, baz  # 문자열? 리스트?
---

참고 문서

• Jekyll - Front Matter
• YAML Specification