← 글 목록

사이트에 마크다운 글 섹션을 만든 과정과 안전장치

만들기 기록6분 분량

사이트 안에 직접 쓰는 글 섹션을 추가하면서, frontmatter 검증과 초안 숨기기, 본문 HTML 이스케이프를 어떻게 설계했는지 정리했습니다.

이 사이트에는 원래 티스토리 글을 모아 보여주는 페이지만 있었습니다. 이번에 사이트 안에서 직접 쓰는 글 섹션(/posts)을 추가했습니다. 글을 마크다운 파일로 저장하고, 목록과 주제별 필터, 개별 글 페이지를 만든 작업입니다. 여기서는 구조를 어떻게 잡았는지, 특히 아직 다듬는 중인 초안이 실수로 공개되지 않도록 넣은 안전장치 세 가지를 정리합니다.

글은 파일 하나가 한 편

글은 content/posts/*.md에 둡니다. 파일 이름이 곧 주소(slug)가 되고, 맨 위의 frontmatter에 제목·설명·날짜·주제·태그를 적습니다. 데이터베이스나 관리 화면 없이 파일만 추가하면 글이 늘어나는 구조입니다. 글이 사이트 저장소 안에 있으니 수정 기록도 코드와 같은 방식으로 남습니다.

주제는 src/lib/topics.ts에 세 가지로 고정했습니다. 만들기 기록(build-log), AI와 일하기(ai-work), 쉽게 읽는 IT(tech-explained)입니다. 글의 topic 값이 이 목록에 없으면 글로 인정하지 않습니다.

export const topics = [
  { slug: "build-log", name: "만들기 기록", /* ... */ },
  { slug: "ai-work", name: "AI와 일하기", /* ... */ },
  { slug: "tech-explained", name: "쉽게 읽는 IT", /* ... */ },
] as const;

주제 목록을 코드 한 곳에 두면 목록 페이지, 주제별 페이지(/posts/topic/[topic]), 글 상단의 주제 표시가 모두 같은 이름을 씁니다.

마크다운 파일이 검증, 초안 걸러내기, HTML 변환을 거쳐 페이지가 되는 네 단계를 위에서 아래로 보여주는 그림
글 파일이 페이지가 되기까지의 네 단계

안전장치 1: 형식이 틀리면 빌드를 멈춘다

글을 직접 쓰다 보면 frontmatter 한 줄을 빠뜨리거나 날짜 형식을 틀리는 실수가 생깁니다. 그래서 src/lib/posts.ts의 parseFile에서 글을 읽을 때마다 형식을 검사합니다. 파일 이름은 영문 소문자·숫자·하이픈만 허용하고, title, description, topic이 비어 있으면 오류를 던집니다. 날짜는 YYYY-MM-DD 형식이어야 하고, 주제는 위의 목록에 있어야 합니다.

if (!getTopic(data.topic)) {
  throw new Error(`${where}: 알 수 없는 topic '${data.topic}'. src/lib/topics.ts를 확인하세요.`);
}

오류를 던지면 빌드가 실패합니다. 잘못된 글이 조용히 빠지거나 깨진 채 배포되는 것보다, 빌드 단계에서 시끄럽게 실패하는 편이 낫다고 판단했습니다. 오류 메시지에는 어느 파일의 무엇이 문제인지 적어서 바로 고칠 수 있게 했습니다.

안전장치 2: 초안은 로컬에서만 보인다

frontmatter에 draft: true를 적은 글은 초안입니다. 코드에서는 NODE_ENV가 production이 아닐 때만 초안을 보여줍니다.

const SHOW_DRAFTS = process.env.NODE_ENV !== "production";
// ...
.filter((p) => SHOW_DRAFTS || !p.draft)

로컬 개발 서버에서는 초안이 목록에 나오고, 글 상단에 "초안이에요"라는 안내가 붙습니다. 배포용 빌드에서는 초안이 목록에서 빠지고, 글 주소도 만들어지지 않습니다. 개별 글 페이지는 dynamicParams = false와 generateStaticParams로 존재하는 글의 주소만 미리 만들기 때문입니다. 초안 글 메타데이터에는 검색 제외(noindex) 설정도 넣어 두었습니다.

개발 서버에서는 초안이 보이고 배포된 사이트에서는 초안이 빠진다는 점을 두 개의 상자로 비교한 그림
초안이 보이는 곳과 보이지 않는 곳

덕분에 새 글을 초안으로 저장해 두고 로컬에서 모양을 확인한 뒤, draft 줄을 지우는 것으로 공개할 수 있습니다. 비유하자면 공개 전에 서랍에 넣어 두는 원고와 같습니다. 서랍 안의 원고는 나(개발 서버)에게만 보입니다.

안전장치 3: 본문의 HTML은 실행하지 않는다

마크다운은 기본적으로 본문에 HTML을 섞어 쓸 수 있습니다. 편리하긴 하지만, 다른 곳에서 복사해 온 내용에 스크립트 태그가 섞여 있으면 그대로 페이지에서 실행될 수 있습니다. 그래서 marked의 렌더러를 바꿔서 HTML 조각을 실행하지 않고 글자 그대로 보이게 했습니다.

const markdown = new Marked({
  gfm: true,
  renderer: {
    html: ({ text }) => escapeHtml(text),
    // image: 캡션이 있으면 figure로 감싼다
  },
});

<, >, &, "를 각각 &lt;, &gt;, &amp;, &quot;로 바꾸는 escapeHtml을 쓰는 단순한 방식입니다. 대신 글에서 HTML 태그로 꾸밀 수는 없습니다. 이미지는 마크다운 문법으로 쓰고, 캡션(이미지의 title 부분)이 있으면 figure와 figcaption으로 감싸도록 렌더러에 따로 규칙을 넣었습니다. 이미지에는 loading="lazy"를 붙여 늦게 불러옵니다.

글이 늘어났을 때를 위한 작은 장치들

  • 읽는 시간: 공백을 뺀 글자 수를 500으로 나눈 값을 분 단위로 보여줍니다. 최소 1분입니다.
  • 대표 이미지: 본문에서 처음 나오는 /로 시작하는 이미지 경로를 SNS 미리보기 이미지로 씁니다.
  • 이전·다음 글: 날짜순으로 정렬한 목록에서 이웃 글을 찾아 글 아래에 링크로 붙입니다. 같은 날짜면 slug 순서로 정렬해서 순서가 흔들리지 않게 했습니다.
  • 구조화 데이터: 글 페이지에 BlogPosting JSON-LD를 넣었습니다. 이때 JSON 안의 꺾쇠 기호(여는 괄호 모양)를 유니코드 이스케이프로 바꿔서, 문자열이 script 태그를 중간에 닫지 못하게 했습니다.
  • 사이트맵과 홈: 발행된 글이 있으면 사이트맵에 포함하고, 홈에는 최신 글을 보여줍니다.

배운 점

글 섹션 자체는 파일을 읽어서 HTML로 바꾸는 단순한 작업입니다. 오래 고민한 부분은 오히려 "잘못된 글이 공개되는 길"을 어떻게 막느냐였습니다. 형식 검증은 빌드 실패로, 초안은 환경 변수로, 본문 HTML은 이스케이프로 각각 한 겹씩 막았습니다. 제가 실수를 하더라도 같은 규칙이 걸러 주고, 규칙이 코드에 있으니 기억에만 기댈 필요가 없다는 점이 가장 마음에 듭니다.

아직 부족한 점도 있습니다. 초안 여부는 환경 변수 하나에 의존하기 때문에, 배포 환경 설정이 바뀌면 이 안전장치도 함께 흔들립니다. 배포 전에 초안이 섞이지 않았는지 따로 확인하는 절차가 있으면 더 안전할 것입니다. 이 사이트의 다른 글은 글 목록에서 볼 수 있습니다.

  • #Next.js
  • #마크다운
  • #블로그
  • #frontmatter
  • #빌드 검증