📘 Markdown(.md) vs MDX(.mdx) 가이드

1. Markdown(.md)이란?

텍스트를 쉽게 꾸미는 문법

README, 블로그 글, 기술 문서 등에서 가장 많이 사용

.md 확장자를 가짐

순수한 텍스트 + 마크다운 문법만 사용 가능

✅ 예시 (post.md)

title: '마크다운 예제 글'
date: '2025-01-01'
tags: ['Markdown', 'Blog']

# 안녕하세요 👋

이 글은 **마크다운**으로 작성되었습니다.

- 리스트 1
- 리스트 2

[링크](https://example.com)

2. MDX(.mdx)란?

Markdown + JSX (리액트 컴포넌트 삽입 가능)

.mdx 확장자를 가짐

마크다운 문법은 그대로 사용하면서, 필요할 때 React 컴포넌트를 직접 불러와 쓸 수 있음

Next.js, Gatsby, Docusaurus 같은 React 기반 프레임워크에서 자주 사용

✅ 예시 (post.mdx)

title: 'MDX 예제 글'
date: '2025-01-02'
tags: ['MDX', 'React']

#MDX 예제 ✨

마크다운 문법은 그대로 쓰면서...

<Button>클릭하세요</Button>

<MyChart data={chartData} />

👉 여기서 <Button>과 <MyChart>는 React 컴포넌트입니다.
즉, 블로그 글 안에서 버튼, 차트, 동적 UI를 직접 넣을 수 있습니다.

3. 공통점

둘 다 Frontmatter(---로 감싼 메타데이터) 사용 가능

글 본문에서 마크다운 문법 (# 제목, 굵게, 리스트) 지원

#4. 차이점 요약

구분	.md	.mdx
기본 기능	텍스트 + 마크다운	텍스트 + 마크다운 + JSX
확장성	정적 문서 작성	리액트 컴포넌트 삽입 가능 (동적)
실행 환경	어디서나 사용 가능 (GitHub, 블로그 등)	React 기반 환경 필요 (Next.js, Gatsby 등)
예시	블로그 글, README	블로그 글 + 인터랙티브 컴포넌트

5. 언제 어떤 걸 써야 할까?

단순히 글만 작성한다면 → .md

글 속에 컴포넌트, 차트, 인터랙티브 기능을 넣고 싶다면 → .mdx

👉 예를 들어:

기술 블로그(문서 위주) → .md면 충분

개발 블로그(코드 실행 버튼, 차트, 동적 UI) → .mdx 권장

#6. Next.js + Contentlayer에서 사용하기

#설치

npm install contentlayer next-contentlayer @mdx-js/react

#next.config.js

const { withContentlayer } = require('next-contentlayer')

module.exports = withContentlayer({
  experimental: {
    appDir: true,
  },
})

#posts/hello.mdx (글 작성)

---
title: 'Hello MDX'
date: '2025-01-03'
---

# Hello World

<Button>클릭!</Button>

#페이지에서 불러오기

import { allPosts } from 'contentlayer/generated'
import { useMDXComponent } from 'next-contentlayer/hooks'

export default function Post({ params }) {
  const post = allPosts.find((p) => p._raw.flattenedPath === params.slug)
  const MDXContent = useMDXComponent(post.body.code)

  return (
    <article>
      <h1>{post.title}</h1>
      <MDXContent />
    </article>
  )
}

✅ 요약

.md = 마크다운 문법만 → 정적 글

.mdx = 마크다운 + React → 동적인 글

둘 다 Frontmatter 지원

Next.js + Contentlayer 같은 환경에서 둘 다 불러올 수 있지만, 컴포넌트를 쓰려면 mdx를 선택해야 함