Markdown 파일 기반 블로그에서 콘텐츠 형식을 지키는 방법
woosday의 글은 데이터베이스 레코드가 아니라 posts/ 폴더의 Markdown 파일이다. 글을 작성하고 수정하는 과정이 단순하고 Git diff로 변경 내용을 확인할 수 있다는 점이 이 구조의 장점이다. 반대로 파일 형식이 조금만 흔들려도 목록, RSS, 사이트맵, 구조화 데이터가 함께 영향을 받는다.
글 하나가 갖는 최소 계약
모든 글은 본문 위에 YAML front matter를 둔다. 현재 사용하는 필드는 다음과 같다.
---
title: 글 제목
date: 2026-09-06
updated: 2026-09-21
category: 운영
tags: [Spring Boot, Markdown]
summary: 검색 결과와 목록에 보여 줄 한 줄 요약
---
title과 date는 목록과 상세 화면의 기본 정보다. category는 메뉴와 카테고리 필터를 결정하고, tags는 관련 글을 연결하는 기준이 된다. summary는 글을 열기 전에 독자가 주제를 판단하도록 돕는다. 내용을 수정했을 때는 updated를 추가해 게시일과 수정일을 구분한다.
필드를 많이 추가하는 것보다 같은 이름과 형식을 반복해서 사용하는 것이 중요하다. 날짜를 2026.09.06처럼 쓰거나 태그를 문자열 하나로 넣으면 파서가 다른 타입으로 해석할 수 있다. 새 글을 만들 때 기존 글의 front matter를 복사하는 이유다.
파일명은 URL의 일부다
파일명은 글의 slug가 된다. 2026-09-06-woosday-markdown-content-contract.md는 /blog/2026-09-06-woosday-markdown-content-contract로 연결된다. 파일명을 나중에 바꾸면 기존 검색 결과와 내부 링크가 끊길 수 있으므로 처음부터 주제를 설명하는 영문 slug를 정한다.
제목을 바꾸는 일과 URL을 바꾸는 일은 분리한다. 오탈자를 고치는 정도라면 front matter의 title만 수정하고 파일명은 유지한다. URL을 꼭 바꿔야 한다면 기존 주소에서 새 주소로 연결하는 방법을 먼저 준비한다.
작성 후 확인 순서
글을 저장한 뒤에는 다음 순서로 확인한다.
- front matter의 구분선이 정확히 두 줄인지 확인한다.
- 제목, 날짜, 카테고리, 요약이 목록에 보이는지 확인한다.
- 코드 블록, 표, 링크가 상세 화면에서 올바르게 렌더링되는지 확인한다.
- 같은 카테고리나 태그의 관련 글 링크가 자연스러운지 확인한다.
- RSS와 사이트맵에 새 URL이 반영되는지 확인한다.
- 제목이 너무 길거나 특수문자 때문에 모바일에서 넘치지 않는지 확인한다.
woosday는 글을 메모리에 캐시한다. 따라서 운영 중 새 글을 추가하거나 수정하면 관리자 화면에서 캐시를 새로고침하거나 애플리케이션을 재시작해야 한다. Docker 이미지에 포함되는 글과 실행 중 볼륨에 저장되는 자료를 구분해 두면 배포 뒤 무엇이 유지되는지도 명확해진다.
파일 기반 구조가 잘 맞는 범위
개인 블로그처럼 작성자가 한 명이고 글의 변경 빈도가 높지 않다면 Markdown과 Git 조합은 충분히 실용적이다. 검색, 카테고리, 관련 글 같은 기능도 애플리케이션 시작 시 파일을 읽어 구성할 수 있다. 별도의 DB 백업과 마이그레이션을 관리하지 않아도 된다는 점도 작다.
다만 여러 사람이 동시에 글을 작성하거나, 관리자 화면에서 복잡한 편집과 초안과 예약 발행을 제공하려면 다른 저장소를 검토해야 한다. 저장 방식은 유행보다 콘텐츠의 변경 방식과 운영 인원에 맞춰 선택하는 것이 맞다.
정리
파일 기반 블로그의 핵심은 Markdown 자체가 아니라 콘텐츠 계약이다. front matter, 파일명, 내부 링크, 캐시 갱신 규칙을 정해 두면 글 수가 늘어도 운영 흐름이 흔들리지 않는다. 새로운 기능을 추가할 때도 먼저 “이 기능이 글 형식과 검색 결과에 어떤 영향을 주는가”를 확인하면 나중에 고칠 범위를 줄일 수 있다.
함께 읽기: