Markdown으로 기술 블로그 운영하기

Markdown은 기술 블로그 운영에 잘 맞는 형식입니다. 문법이 단순하고, Git으로 변경 이력을 관리하기 쉬우며, 정적 사이트 생성기와 궁합이 좋습니다. 개발 문서, 튜토리얼, 운영 회고, 체크리스트처럼 구조가 중요한 글을 빠르게 작성할 수 있다는 장점도 있습니다. 하지만 파일을 많이 만들수록 제목 규칙, frontmatter, 이미지 위치, 내부 링크, 배포 전 검수 기준이 없으면 블로그 품질이 금방 흔들립니다.

이 글은 서민혁닷컴 같은 Markdown 기반 기술 블로그를 꾸준히 운영하기 위한 실무 가이드입니다. 글을 잘 쓰는 법만이 아니라, 파일 단위 콘텐츠를 제품처럼 관리하는 방법에 초점을 맞춥니다.

Markdown 블로그의 기본 구조

정적 블로그에서는 보통 src/content/posts 같은 디렉터리에 Markdown 파일을 두고, 파일 이름을 slug로 사용합니다. 예를 들어 markdown-tech-blog.md는 /posts/markdown-tech-blog 주소가 됩니다. 파일명은 짧고 의미 있게, 영문 소문자와 하이픈을 사용하면 관리하기 쉽습니다.

각 Markdown 파일 상단에는 frontmatter가 들어갑니다. frontmatter는 제목, 설명, 발행일, 카테고리, 태그, 대표 이미지 같은 메타데이터를 담습니다. 이 값은 목록 화면, 상세 페이지, SEO 태그, 관련 글 영역에서 사용됩니다.

항목	예시	운영 기준
title	글 제목	검색 의도와 실제 내용 일치
description	요약 설명	목록과 메타 설명에 사용
pubDate	발행일	정렬과 구조화 데이터 기준
category	카테고리	너무 많이 늘리지 않기
tags	주제 키워드	3~5개 정도로 유지
heroImage	대표 이미지	파일 존재와 경로 확인
relatedSlugs	관련 글	실제 독서 흐름 기준

frontmatter는 자유롭게 적는 메모가 아니라 사이트 스키마와 연결된 데이터입니다. 필드명이 틀리거나 날짜 형식이 깨지면 빌드가 실패할 수 있습니다. 따라서 글을 작성할 때 템플릿을 복사해서 시작하고, 배포 전 검증 명령을 실행하는 습관이 필요합니다.

좋은 글 구조 만들기

기술 블로그 글은 독자가 문제를 해결하기 위해 찾아옵니다. 서론에서 상황과 대상 독자를 분명히 말하고, 본문에서는 절차와 판단 기준을 나누고, 마지막에는 체크리스트와 주의점을 제공하는 구조가 실용적입니다.

추천 구조는 다음과 같습니다.

어떤 문제를 다루는지 설명합니다.
독자가 먼저 알아야 할 개념을 짧게 정리합니다.
단계별 실행 절차를 제시합니다.
표나 체크리스트로 판단 기준을 압축합니다.
실무에서 자주 생기는 실수를 정리합니다.
관련 글로 다음 학습 경로를 연결합니다.

예를 들어 배포 글이라면 단순히 명령어를 나열하기보다 빌드 결과, 배포 설정, 캐시, 도메인, SEO 파일 점검을 함께 다뤄야 합니다. 실제 배포 흐름은 Cloudflare Workers에 정적 사이트 올리는 법처럼 여러 단계가 연결되어 있기 때문입니다.

내부 링크 전략

내부 링크는 독자의 탐색을 돕고 검색엔진이 사이트 구조를 이해하게 만듭니다. 새 글을 발행할 때는 최소 두세 개의 관련 글을 연결하고, 기존 글에서도 새 글을 연결할 수 있는지 확인합니다. 단, 관련 없는 링크를 억지로 넣으면 독서 흐름이 끊깁니다.

좋은 내부 링크 문구는 대상 글의 의미를 담고 있습니다. “자세히 보기”보다 정적 사이트와 SSR 선택 기준처럼 링크만 봐도 무엇을 설명하는지 알 수 있는 문구가 좋습니다. Git 기반 운영 흐름을 다룰 때는 Git과 GitHub로 커밋하고 푸시하기처럼 다음 행동과 연결되는 글을 추천할 수 있습니다.

관련 글을 정할 때는 다음 질문을 해 보세요.

이 글을 읽은 사람이 다음에 해결할 문제는 무엇인가?
지금 글의 전제 지식을 더 자세히 설명한 글이 있는가?
반대로 이 글을 실무에 적용하는 후속 글이 있는가?
같은 카테고리지만 내용이 중복되는 글은 아닌가?

이미지와 ALT 관리

대표 이미지는 목록과 공유 화면에서 글의 인상을 결정합니다. 하지만 이미지가 크거나 alt가 비어 있으면 성능과 접근성에 나쁜 영향을 줄 수 있습니다. Markdown 블로그에서는 이미지 파일을 public 디렉터리에 두고, frontmatter에서 경로를 참조하는 방식이 흔합니다.

이미지 운영 기준은 다음과 같습니다.

대표 이미지는 모든 글에서 같은 비율을 유지합니다.
파일명은 주제를 설명하는 영문 하이픈 형식으로 작성합니다.
alt는 “이미지”가 아니라 이미지가 전달하는 의미를 설명합니다.
장식용 이미지는 가능한 CSS 배경 또는 빈 alt 정책을 검토합니다.
실제 표시 크기보다 과하게 큰 이미지를 사용하지 않습니다.

접근성 기준은 웹 접근성 기본 — 제목·ALT·대비와 함께 점검하면 좋습니다. Markdown 문서에서는 이미지 삽입이 쉬운 만큼, 대체 텍스트를 빠뜨리는 실수도 자주 발생합니다.

배포 전 검수 체크리스트

글을 작성한 뒤에는 맞춤법만 볼 것이 아니라 사이트 데이터로 정상 동작하는지 확인해야 합니다.

파일명이 slug 규칙을 따르는가?
frontmatter 필드가 스키마와 일치하는가?
제목과 description이 본문 내용과 맞는가?
H2, H3 구조가 논리적으로 이어지는가?
내부 링크가 /posts/slug 형식으로 연결되는가?
이미지 경로와 alt가 올바른가?
표가 모바일에서도 읽을 수 있을 만큼 간결한가?
코드 블록에 민감한 값이 포함되어 있지 않은가?
빌드가 성공하고 목록에 글이 표시되는가?

정적 사이트는 배포 전 빌드가 곧 품질 게이트입니다. Markdown 문법이 조금 깨져도 브라우저에서는 이상하게 보일 수 있고, frontmatter 오류는 빌드를 중단시킬 수 있습니다. 자동화된 빌드 검사를 꼭 실행하세요.

운영 워크플로

혼자 쓰는 블로그라도 Git 워크플로를 적용하면 안정성이 높아집니다. 새 글은 브랜치에서 작성하고, 미리보기로 확인하고, 커밋 메시지에 어떤 글을 추가했는지 남깁니다. 여러 사람이 함께 운영한다면 리뷰 기준을 문서화해야 합니다. 제목 톤, 카테고리 기준, 이미지 스타일, 내부 링크 정책이 사람마다 달라지면 사이트 전체의 일관성이 떨어집니다.

Markdown 블로그는 단순하지만, 글이 많아질수록 콘텐츠 데이터베이스처럼 동작합니다. 파일명, 메타데이터, 링크가 모두 구조화된 자산이므로 작은 규칙을 꾸준히 지키는 것이 중요합니다.

실무 주의점

첫째, Markdown 문법에 HTML을 과하게 섞지 마세요. 특별한 컴포넌트가 필요한 경우는 있지만, 글마다 임의의 HTML을 넣으면 디자인과 접근성 관리가 어려워집니다. 둘째, 태그를 너무 많이 만들지 마세요. 비슷한 태그가 늘어나면 탐색 가치가 떨어집니다. 셋째, 발행 후에도 오래된 글을 업데이트할 계획을 세우세요. 기술 글은 시간이 지나면 명령어, 화면, API가 바뀝니다.

마지막으로 좋은 블로그 운영은 새 글을 많이 쓰는 것만이 아닙니다. 기존 글을 연결하고, 낡은 정보를 고치고, 독자가 다음 행동으로 넘어갈 수 있게 구조를 정리하는 일입니다. Markdown은 이 과정을 빠르고 투명하게 만들어 주는 도구입니다.