빠른 비교

import { Callout } from './components/Callout.jsx'

# 설치 가이드

일반 문장은 Markdown으로 작성합니다.

<Callout tone="warning">
  Node.js 버전을 먼저 확인하세요.
</Callout>

현재 버전: {version}

문법

MDX는 Markdown에 JSX와 JavaScript 표현식을 섞는 형식이다

MDX는 일반 Markdown 문서에 JSX component, JavaScript expression, ESM import와 export를 함께 쓸 수 있게 만든 형식입니다. 제목, 문단, 목록, 코드 블록처럼 본문 중심의 내용은 Markdown이 자연스럽고, 반복되는 UI나 동적인 표시가 필요한 부분은 component가 적합합니다.

import { ApiStatus } from './ApiStatus.jsx'

## API 상태

<ApiStatus endpoint="/health" />

일반 .md 파일에서는 위 JSX가 그대로 텍스트로 보이거나 HTML처럼 처리될 수 있습니다. .mdx 파일은 빌드 단계에서 JavaScript로 컴파일되므로 문서 렌더러가 MDX를 지원하는지 먼저 확인해야 합니다.

중괄호는 JavaScript expression 경계다

MDX에서 {...}는 JavaScript expression을 평가하는 경계입니다. 단순히 { 문자를 보여 주려는 의도라면 escape하거나 문자열 표현식으로 감싸야 합니다. 본문에 수식, JSON 예시, 템플릿 문법이 자주 나오는 기술 문서에서는 이 경계가 빌드 오류를 만들기 쉽습니다.

<!-- expression -->
빌드 번호: {buildNumber}

<!-- 리터럴 중괄호를 보여 줄 때 -->
\{name\}

<!-- 또는 문자열 expression -->
{'{name}'}

특히 JSON 예시를 일반 문단에 직접 넣으면 {}가 expression으로 해석될 수 있습니다. 구조화된 예시는 fenced code block 안에 넣는 편이 안전합니다.

HTML이 아니라 JSX 규칙을 따른다

MDX에서 <Component />나 <div>는 HTML 문자열이 아니라 JSX로 해석됩니다. React 기반 환경에서는 class가 아니라 className을 쓰고, 닫는 태그가 필요한 요소는 명확히 닫아야 합니다. HTML 주석도 그대로 쓰기보다 {/* comment */} 형태의 JavaScript 주석을 사용합니다.

<!-- 일반 HTML처럼 보이지만 MDX에서는 JSX 규칙을 따름 -->
<div className="note">
  설명을 넣습니다.
</div>

{/* MDX 안의 주석 */}

Markdown의 관대한 문법과 달리 JSX는 문법 오류에 민감합니다. 태그가 닫히지 않거나 prop 값이 잘못되면 문서 전체 빌드가 실패할 수 있습니다.

선택 기준

주의사항

<!-- 깨지기 쉬운 예: 닫히지 않은 component -->
<Callout tone="warning">
  본문