글을 가볍게 남기는 방식

블로그를 운영할 때 가장 중요한 도구는 에디터가 아니라 흐름입니다. 글을 쓰고, 검토하고, 배포하고, 나중에 수정하는 과정이 무거우면 기록은 곧 멈춥니다. Markdown 파일과 Git 이력을 중심으로 두면 글도 코드처럼 작게 바꾸고 되돌아볼 수 있습니다.

목표는 단순합니다. 글 하나를 추가하면 자동으로 페이지가 생기고, 제목과 설명 같은 메타데이터가 빠지면 빌드 단계에서 발견되며, 배포된 HTML은 검색엔진이 바로 읽을 수 있어야 합니다.

Markdown을 선택한 이유

Markdown은 기능이 많아서가 아니라 제약이 좋아서 선택했습니다. 글의 본질은 제목, 문단, 목록, 코드, 링크입니다. 초기 기술 블로그에 필요한 대부분의 표현은 이 범위 안에서 해결됩니다.

또 하나의 장점은 변경 이력입니다. CMS에서 글을 수정하면 결과만 남기 쉬운데, 저장소 안의 Markdown은 코드와 같은 방식으로 리뷰할 수 있습니다. 제목을 바꾼 이유, 설명을 다듬은 시점, 태그를 정리한 흔적이 커밋에 남습니다.

이 방식은 글을 “콘텐츠 데이터”로 다룰 수 있게 만듭니다. 예를 들어 각 글의 frontmatter에는 다음 정보가 들어갑니다.

title: 검색 결과와 브라우저 제목에 쓰이는 문장
description: 메타 설명과 카드 요약에 쓰이는 문장
lang: 한글/영어 URL과 대체 링크를 결정하는 값
translationKey: 같은 글의 번역본을 연결하는 키
tags: 목록 필터, RSS category, 구조화 데이터에 쓰이는 키워드
publishedAt, updatedAt: 발행일과 수정일

사람이 글을 쓰지만, 배포 단계에서는 이 값들이 사이트 구조를 만듭니다.

실제 글 파일은 다음처럼 시작합니다.

---
title: "글을 가볍게 남기는 방식"
description: "기록이 부담이 되지 않도록 쓰고 고치는 흐름을 단순하게 정리했습니다."
lang: "ko"
translationKey: "markdown-writing-flow"
category: "Engineering"
tags: ["markdown", "github-pages", "astro"]
publishedAt: "2026-07-01"
updatedAt: "2026-07-01"
draft: false
---

여기서 중요한 값은 translationKey입니다. 같은 주제의 한국어 글과 영어 글이 같은 키를 공유하면, 빌드 단계에서 서로를 alternate 페이지로 연결할 수 있습니다.

빌드 전에 검증해야 하는 것

Markdown 블로그의 약점은 자유도가 높다는 점입니다. 파일을 아무렇게나 추가해도 겉보기에는 글처럼 보일 수 있습니다. 그래서 자유도를 줄이는 장치가 필요합니다.

Astro Content Collections로 글 스키마를 정의하면 제목, 설명, 언어, 발행일, 태그 같은 값이 빌드 전에 검증됩니다. 잘못된 언어 코드나 비어 있는 제목은 배포 전에 잡는 것이 맞습니다. 배포된 뒤 검색엔진이 잘못된 canonical을 가져가는 것보다 훨씬 싸게 고칠 수 있기 때문입니다.

다국어도 같은 이유로 느슨하게 두지 않습니다. translationKey가 같은 글은 서로 alternate 링크로 연결됩니다. 한국어 글을 보고 있는 검색엔진과 사용자는 영어 대체 페이지가 있는지 알 수 있고, 반대도 마찬가지입니다.

배포 흐름

현재 흐름은 이렇게 동작합니다.

src/content/posts/{ko,en} 아래에 Markdown 파일을 추가합니다.
frontmatter가 스키마를 통과하는지 확인합니다.
Astro가 글 목록, 상세 페이지, sitemap, RSS를 정적 파일로 생성합니다.
GitHub Actions가 빌드 결과를 GitHub Pages에 배포합니다.

이 구조에서는 새 글을 쓰기 위해 서버를 만질 필요가 없습니다. 저장소에 글이 들어오면 정적 HTML이 다시 만들어집니다. 운영 서버가 글을 읽어 렌더링하는 방식이 아니기 때문에 트래픽이 조금 늘어도 비용 구조가 단순합니다.

운영 관점에서 보면 흐름은 이렇습니다.

단계	사람이 하는 일	자동화가 하는 일
작성	Markdown 파일 추가	frontmatter 스키마 검증
리뷰	제목, 설명, 내부 링크 확인	테스트에서 콘텐츠 기준 확인
빌드	GitHub에 push	Astro가 HTML, RSS, sitemap 생성
배포	배포 결과 확인	GitHub Pages가 정적 파일 제공

실패도 빨리 드러나야 합니다. 예를 들어 category에 허용되지 않은 값을 넣으면 글이 조용히 배포되는 것이 아니라 빌드가 실패해야 합니다.

---
title: "실패해야 하는 글"
description: "카테고리가 스키마에 없기 때문에 배포 전에 막혀야 합니다."
lang: "ko"
translationKey: "invalid-category-example"
category: "Random"
tags: ["example"]
publishedAt: "2026-07-01"
draft: false
---

이런 실패는 불편해 보여도 필요합니다. 검색엔진이 잘못된 페이지를 가져간 뒤 수정하는 것보다, 배포 전에 멈추는 것이 훨씬 싸기 때문입니다.

나중에 바뀔 수 있는 부분

Markdown을 쓴다고 해서 영원히 단순한 블로그에 갇히는 것은 아닙니다. 검색이 필요해지면 정적 인덱스를 붙일 수 있고, 편집 UI가 필요해지면 headless CMS를 연결할 수 있습니다. 중요한 것은 첫 버전부터 그 가능성을 위해 서버를 켜두는 것이 아니라, 필요한 순간에 붙일 수 있도록 경계를 정리해 두는 것입니다.

그래서 지금의 선택은 “Markdown이면 충분하다”가 아니라 “현재 문제에는 Markdown과 정적 빌드가 가장 비용 대비 효과적이다”에 가깝습니다. 이 차이를 놓치지 않으려고 합니다.

이어서 읽기

이 방식이 검색 노출과 어떻게 연결되는지는 GitHub Pages로 블로그를 만들면 SEO에 불리할까?에서 다룹니다. 기술 선택의 더 큰 배경은 정적 블로그를 선택한 이유를 함께 보면 흐름이 이어집니다.