Markdown, MDX, Headless CMS 중 1인 개발 블로그에 맞는 선택법

블로그를 처음 만들 때 가장 자주 나오는 질문 중 하나가 바로 이것이다. “글은 Markdown으로 쓸까, MDX로 갈까, 아니면 처음부터 Headless CMS를 붙일까?” 겉으로 보기엔 단순한 도구 선택처럼 보이지만, 실제로는 작성 방식, 배포 파이프라인, 협업 가능성, 나중에 사이트를 확장하는 방식까지 함께 결정하는 문제에 가깝다.

처음에는 대개 이렇게 생각한다. Markdown은 단순해서 좋아 보이고, MDX는 뭔가 더 유연해 보이고, Headless CMS는 있어 보인다. 그런데 1인 개발 블로그라는 조건을 넣고 다시 보면 결론이 꽤 달라진다. 혼자 운영하는 블로그는 “기능이 많을수록 유리한 제품”이 아니라, “운영 리듬을 방해하지 않는 시스템”이 더 좋은 선택이기 때문이다.

나는 이 주제에서 가장 중요한 질문이 “무엇이 가장 강력한가”가 아니라 “무엇이 지금 내 운영 방식과 가장 잘 맞는가”라고 생각한다. 같은 Next.js 블로그라도 혼자 글을 쓰고 코드와 함께 관리하는 사람, 나중에 인터랙티브한 컴포넌트를 많이 넣고 싶은 사람, 비개발자와 함께 글을 편집해야 하는 사람은 답이 다를 수밖에 없다.

Next.js 공식 문서는 MDX를 App Router에서 직접 사용할 수 있도록 안내하고 있고, pageExtensions 설정과 @next/mdx 구성을 통해 .mdx 파일을 페이지처럼 다룰 수 있다고 설명한다. MDX 자체 공식 문서는 “Markdown 안에서 JSX를 사용할 수 있다”는 점을 강점으로 제시한다. 반면 Contentful은 API-first CMS를 중심으로 여러 API를 통해 콘텐츠를 읽고 쓸 수 있다고 설명하고, Sanity는 구조화된 콘텐츠를 위한 programmable content platform 성격을 강하게 내세운다. 즉 세 가지는 표면적으로 비슷해 보여도, 실제로는 문제를 푸는 방식이 서로 다르다.

기반 설계작성 워크플로우

Markdown, MDX, Headless CMS 중 1인 개발 블로그에 맞는 선택법

혼자 블로그를 오래 운영할 생각이라면 작성 방식부터 너무 무겁게 시작할 필요는 없다. Markdown, MDX, Headless CMS를 유지보수와 확장성 기준으로 비교한다.

핵심 1

혼자 오래 운영할 거라면 Markdown에서 시작해도 충분하다

핵심 2

세 가지를 가장 짧게 설명하면

핵심 3

가장 먼저 봐야 하는 기준 4가지

작성 워크플로우기반 설계markdown mdx headless cms

혼자 오래 운영할 거라면 Markdown에서 시작해도 충분하다

아주 짧게 말하면 나는 이렇게 추천한다.

• 혼자 운영하고 글과 코드를 Git으로 함께 관리할 수 있다면 Markdown
• 콜아웃, 데모 컴포넌트, 커스텀 블록이 자주 필요하다면 MDX
• 비개발자 편집자, 승인 흐름, 멀티채널 배포가 필요하다면 Headless CMS

즉 “처음부터 Headless CMS를 붙이는 것이 더 프로답다”는 식의 접근은 1인 개발 블로그에는 오히려 과한 경우가 많다. 운영 리듬이 단순한 상태에서는 Markdown이 가장 싸고, 가장 단단하고, 가장 예측 가능하다. 여기에 필요한 만큼만 MDX나 CMS를 나중에 붙이는 편이 더 낫다.

세 가지를 가장 짧게 설명하면

이 표만 보면 MDX나 CMS가 더 상위 개념처럼 느껴질 수 있다. 하지만 실제 운영에서는 “더 강력하다”는 장점이 곧 “더 많은 결정과 유지보수가 필요하다”는 뜻이기도 한다.

가장 먼저 봐야 하는 기준 4가지

내가 1인 개발 블로그에서 이 셋을 고를 때 가장 중요하게 보는 기준은 아래 네 가지다.

1. 글을 누가 쓰는가

혼자 다 쓰는가, 아니면 비개발자도 들어오는가. 이 질문 하나로 사실 절반이 결정된다. 혼자 쓰고 Git에 익숙하다면 Markdown이나 MDX로 충분한 경우가 많다. 반대로 비개발자가 브라우저에서 바로 편집해야 한다면 Headless CMS가 유리해진다.

2. 글 안에 React 컴포넌트가 얼마나 자주 필요한가

기술 블로그라고 해서 무조건 MDX가 필요한 것은 아니다. 대부분의 글은 코드 블록, 표, 이미지, 인용문 정도면 충분하다. 하지만 경고 박스, 탭 UI, 데모 컴포넌트, 제품 카드처럼 재사용 블록을 글 안에 자주 넣고 싶다면 MDX의 가치가 커진다.

3. 운영 복잡도를 얼마나 감당할 수 있는가

Headless CMS는 분명 편한 점이 많지만, 계정 관리, API 키, 프리뷰, 스키마, 요금제, 배포 훅, 이미지 처리 같은 추가 운영 요소가 붙는다. 블로그 자체보다 CMS 설정에 시간을 더 쓰게 되면 본말이 바뀔 수 있다.

4. 이 블로그가 앞으로 어디까지 확장될 것인가

아주 단순한 기술 기록이라면 Markdown으로 오래 가도 문제가 없다. 반면 나중에 문서, 릴리즈 노트, 제품 소개, 다국어 콘텐츠, 여러 작성자, API 재사용까지 계획하고 있다면 CMS가 유리해질 수 있다.

Markdown이 가장 좋은 선택인 경우

1인 개발 블로그에 가장 자주 맞는 답은 여전히 Markdown다. 이유는 단순하다. 파일 기반이라 구조가 예측 가능하고, Git 히스토리와 함께 관리하기 쉽고, 글 원문이 플랫폼에 묶이지 않기 때문이다. 특히 지금처럼 Next.js 블로그를 직접 만들고 있다면, content/articles/*.md 형태로 두고 frontmatter만 붙여도 꽤 단단한 운영 체계를 만들 수 있다.

예를 들어 이런 식이다.

---
title: "새 글 제목"
summary: "아카이브에 보여줄 요약"
publishedAt: "2026-04-08"
---

## 왜 이 글이 필요한가

본문...

Markdown의 가장 큰 장점은 “글 시스템이 과해지지 않는다”는 데 있다. 작성자가 곧 개발자라면 브라우저 기반 WYSIWYG보다 텍스트 파일이 오히려 더 빠를 수 있다. 글을 쓰고, 커밋하고, 배포하면 끝이다. 백업도 쉽고, 옮기기도 쉽고, 특정 서비스에 종속되지도 않다.

이 방식은 특히 이전 글에서 정리한 폴더 구조처럼 콘텐츠와 라우트를 분리해두었을 때 더 강하다. src/app는 라우트와 레이아웃만 담당하고, 실제 글 원문은 content/articles에서 읽어오도록 만들면 운영 구조가 꽤 깔끔해진다.

다만 Markdown에도 한계는 있다. 글 안에 복잡한 React 컴포넌트를 넣고 싶을 때 금방 답답해지고, 글 작성자가 늘어나면 Git 기반 편집이 부담이 될 수 있다. 즉 Markdown은 강력하지만, 어디까지나 “단순한 글 발행 시스템”에서 가장 좋다.

MDX가 빛나는 경우

MDX는 Markdown의 장점은 유지하면서 React 컴포넌트를 글 안에 직접 섞을 수 있게 해준다. Next.js 공식 문서도 App Router에서 @next/mdx를 사용해 .md와 .mdx를 페이지 확장자로 포함할 수 있다고 안내한다.

예를 들어 Next.js 문서의 기본 구성은 이런 식이다.

import createMDX from "@next/mdx";
import type { NextConfig } from "next";

const withMDX = createMDX();

const nextConfig: NextConfig = {
  pageExtensions: ["js", "jsx", "md", "mdx", "ts", "tsx"],
};

export default withMDX(nextConfig);

MDX의 장점은 분명하다. 예를 들어 기술 글 안에 이렇게 커스텀 컴포넌트를 넣을 수 있다.

## 이 설정이 중요한 이유

<Callout tone="warning">
  canonical 설정이 잘못되면 검색 결과가 분산될 수 있다.
</Callout>

이건 일반 Markdown만으로는 다루기 까다로운 영역이다. 그래서 경고 박스, 비교 카드, 인터랙티브 데모, 작은 계산기, 제품 상태 배지 같은 것을 자주 넣고 싶다면 MDX는 확실히 매력적이다.

하지만 MDX는 “Markdown보다 조금 더 유연한 포맷”이 아니라, 운영 관점에서는 사실상 “콘텐츠에 코드 실행 맥락이 섞이는 방식”이다. 여기서부터 관리 난도가 조금씩 올라간다. 작성자가 JSX 문법을 이해해야 하고, 빌드 중 오류 가능성도 생기고, 컴포넌트 API가 바뀌면 예전 글이 깨질 수 있다.

그래서 나는 MDX를 “처음부터 무조건 채택할 기본값”보다는 “Markdown이 아쉽다고 느낀 뒤 추가하는 확장 레이어”에 더 가깝게 본다. 모든 글이 MDX일 필요는 없다. 오히려 블로그 전체를 MDX로 시작해놓고 실제론 대부분 평범한 본문만 쓰게 되면, 복잡성만 늘어난 경우도 꽤 많다.

Headless CMS가 맞는 경우

Headless CMS는 글을 파일이 아니라 콘텐츠 API로 관리하는 접근이다. Contentful은 API-first CMS 문맥에서 Content Delivery API, Management API, Preview API, GraphQL Content API 등을 제공한다고 안내한다. Sanity는 구조화된 콘텐츠를 저장하고, Studio와 스키마 기반 워크플로우를 구성할 수 있는 플랫폼이라는 점을 강조한다.

이 방식이 강한 이유는 명확하다.

• 작성자가 브라우저에서 바로 편집 가능
• 승인 흐름과 역할 분리가 가능
• 콘텐츠를 웹사이트 외 다른 채널에도 재사용 가능
• 프리뷰와 스키마 기반 필드 구성이 가능

예를 들어 Contentful 같은 시스템을 붙이면 글 본문을 이렇게 API로 읽는 식의 흐름이 된다.

export async function getPostsFromCMS() {
  const space = process.env.CONTENTFUL_SPACE_ID;
  const token = process.env.CONTENTFUL_DELIVERY_TOKEN;

  const response = await fetch(
    `https://cdn.contentful.com/spaces/${space}/entries?content_type=blogPost`,
    {
      headers: {
        Authorization: `Bearer ${token}`,
      },
      next: { revalidate: 300 },
    },
  );

  if (!response.ok) {
    throw new Error("콘텐츠를 불러오지 못했다.");
  }

  return response.json();
}

이 구조는 “사이트와 콘텐츠 시스템이 분리되어 있다”는 점에서 분명 유연한다. 다만 1인 개발 블로그 기준으로는 단점도 분명하다. 설정해야 할 것이 많고, 글 하나 쓰기 전에 CMS 스키마와 모델링을 고민해야 하며, 콘텐츠와 프론트엔드가 서로 다른 두 시스템으로 나뉘기 때문에 디버깅 지점도 늘어난다.

즉 Headless CMS는 좋은 도구지만, “혼자 직접 쓰고 직접 배포하는 기술 블로그”라는 조건에서는 너무 이른 최적화가 되는 경우가 많다. 실제로 글을 꾸준히 쓰는 게 더 중요한 단계라면, 작성 경험이 무거워질수록 오히려 발행 빈도가 떨어질 수 있다.

그럼 1인 개발 블로그에는 무엇을 추천하는가

내 추천은 상당히 명확하다.

1단계: Markdown으로 시작

혼자 운영하는 초반에는 이게 가장 좋다. 구조가 단순하고, 백업이 쉽고, Git과 궁합이 좋고, 비용이 거의 없다.

2단계: 필요할 때만 MDX 추가

경고 박스, 데모 컴포넌트, 커스텀 비교 블록이 자주 필요해지면 그때 MDX를 검토한다. 모든 글을 MDX로 바꾸기보다, 필요한 글만 선택적으로 쓰는 방식도 충분히 가능하다.

3단계: 정말 편집 워크플로우가 필요해질 때 CMS 검토

비개발자 작성자, 승인 흐름, 다국어 구조화 콘텐츠, API 재사용 필요가 분명해질 때 Headless CMS로 넘어가는 게 낫다. 지금 당장은 좋아 보여도, 운영 이유가 명확하지 않다면 너무 일찍 붙이지 않는 편이 좋다.

정리하면 이렇다.

내가 실제로 고를 때 마지막으로 확인하는 질문

• 작성자가 개발자인가
• 글 안에 React 컴포넌트가 정말 자주 필요한가
• 브라우저 편집 UI가 꼭 필요한가
• API 기반 콘텐츠 재사용이 당장 필요한가
• 운영 복잡도가 늘어나도 발행 빈도를 유지할 자신이 있는가

이 다섯 질문 중 대부분이 “아직 아니다”라면, 대개 Markdown으로 시작하는 게 맞다.

마무리

Markdown, MDX, Headless CMS는 우열을 가리는 도구가 아니라, 서로 다른 운영 문제를 푸는 방식이다. 1인 개발 블로그라면 보통 가장 먼저 필요한 것은 화려한 편집 시스템이 아니라 꾸준히 발행할 수 있는 단순한 구조다. 그런 점에서 Markdown은 여전히 가장 현실적인 기본값이고, MDX는 필요한 순간에 추가하는 확장 레이어, Headless CMS는 운영 규모가 달라졌을 때 검토하는 다음 단계에 가깝다.

혼자 만드는 기술 블로그에서 중요한 건 시스템이 커 보이는 것이 아니라, 글이 계속 나오고 구조가 오래 버티는 것이다. 내 기준에서는 그래서 “Markdown으로 시작하고, 아쉬운 지점이 분명해질 때 MDX나 CMS로 올라가는 방식”이 가장 안정적인 선택이다.

참고 문서

• Next.js MDX 가이드
• MDX 공식 문서
• Contentful API 가이드
• Sanity 공식 문서