검색어를 입력하면 실시간으로 용어와 글을 찾습니다.

v2.0 Playbook·Modern Web Tech

MDX 렌더링 에러 트러블슈팅 및 작성 수칙 가이드

ReadMe의 MDX 에러 가이드를 기반으로 HTML에서 JSX로의 전환 규칙, 닫는 태그, 카멜케이스 속성, 주석 및 중괄호 처리부터 Astro 5 환경에서 발생하는 줄바꿈, 꺾쇠괄호, 특수문자 에러 예방 수칙까지 총정리합니다.

작성자: ·분류: Modern Web Tech··구글 검색 선호 출처 등록
📖 목차 (TABLE OF CONTENTS)펼치기 / 접기

본 문서는 mktg.kr 프로젝트의 블로그 아티클 및 엔지니어링 문서 작성 시 발생할 수 있는 MDX 렌더링 오류의 근본 원인을 분석하고, 안전하게 문서를 작성하기 위한 표준 수칙과 트러블슈팅 방법을 다룹니다.

글로벌 개발자 문서 플랫폼 ReadMe의 MDX 트러블슈팅 가이드에서 다루는 표준 문법 규칙을 충실히 반영함과 동시에, Astro 5 및 Rollup/Vite 번들러 환경에서 겪게 되는 실무적인 파싱 오류 사례(JSX 속성 줄바꿈, 꺾쇠괄호 오인식, 컴포넌트 격리 등)를 체계적으로 정리했습니다.


1. MDX와 HTML의 핵심 차이 및 파싱 메커니즘

MDX는 단순한 마크다운(Markdown) 파서와 달리, 마크다운 본문 사이에 React/Astro의 JSX 구문을 직접 삽입하여 실행할 수 있는 하이브리드 포맷입니다.

flowchart LR
    A["MDX 원본 문서 (.mdx)"] --> B["Acorn / Remark 파서"]
    B --> C["JSX 추상 구문 트리 (AST)"]
    C --> D["Vite / Rollup 번들러"]
    D --> E["정적 HTML / SSR 렌더링"]

일반 HTML 파서는 문법적으로 닫히지 않은 태그나 잘못된 속성이 있어도 브라우저가 관대하게(Forgiving Parsing) 추측하여 렌더링하지만, MDX는 JavaScript 컴파일러(Acorn/Babel)를 거치므로 엄격한 ECMAScript 문법 검사를 수행합니다. 사소한 닫는 태그 누락이나 속성 따옴표 오기 하나만으로도 사이트 전체의 정적 빌드(astro build)가 전면 중단(Build Failed)됩니다.


2. ReadMe 기반 핵심 MDX 오류 유형과 해결법

ReadMe의 Troubleshoot MDX Errors 규격에 정의된 5가지 핵심 전환 원칙과 해결책입니다.

1) 닫는 태그(Closing Tags) 및 빈 요소(Void Elements)

JSX 문법에서는 모든 태그가 명시적으로 닫혀야 합니다. HTML에서 관행적으로 닫지 않고 사용하던 빈 요소(Void Elements)는 반드시 셀프 클로징(<tag />) 처리를 해야 합니다.

구분 잘못된 마크다운 (HTML 관행) 올바른 MDX (JSX 표준)
줄바꿈 <br> <br />
이미지 <img> 또는 <img src="..."> <img src="..." />
구분선 <hr> <hr />
입력폼 <input type="text"> <input type="text" />

또한 <p>, <li>, <option>, <td>, <tr> 처럼 HTML에서 닫는 태그 생략이 허용되던 블록 태그도 MDX에서는 100% 닫는 태그를 명시해야 합니다.

{/* ❌ 오류 발생: <li> 태그가 닫히지 않음 */}
<ul>
  <li>첫 번째 항목
  <li>두 번째 항목
</ul>

{/* ✅ 올바른 작성법: 모든 태그를 명시적으로 닫음 */}
<ul>
  <li>첫 번째 항목</li>
  <li>두 번째 항목</li>
</ul>

2) 속성 명명 규칙(Attributes)과 카멜케이스(camelCase)

HTML 속성은 대부분 소문자 또는 하이픈(kebab-case)을 사용하지만, JSX 속성은 자바스크립트 식별자 규칙에 따라 **카멜케이스(camelCase)**로 작성해야 합니다.

  • 카멜케이스 변환 대상: tabindex ➔ tabIndex, autocomplete ➔ autoComplete, autoplay ➔ autoPlay, fill-rule ➔ fillRule
  • 예외 대상 (하이픈 유지): 웹 접근성 속성(aria-*)과 커스텀 데이터 속성(data-*)은 그대로 유지합니다. (aria-label, data-theme 등)
  • class vs className: React 기반 프레임워크에서는 className이 필수이지만, Astro 컴포넌트에서는 class도 완벽히 지원합니다. 단, 범용 리액트 컴포넌트 혼용 시 호환성에 주의해야 합니다.

인라인 스타일(style)은 문자열이 아닌 객체로 작성

HTML에서는 style="margin-left: auto; color: red;"와 같이 문자열로 작성했지만, MDX/JSX에서는 반드시 JavaScript 객체 이중 중괄호(style={{ ... }}) 형태로 작성해야 합니다.

{/* ❌ 오류 발생: 문자열 스타일은 JSX에서 파싱 에러 유발 */}
<div style="margin-left: auto; font-size: 14px;">텍스트</div>

{/* ✅ 올바른 작성법: 객체 및 카멜케이스 속성 적용 */}
<div style={{ marginLeft: 'auto', fontSize: '14px' }}>텍스트</div>

[!NOTE] <style> 태그 블록 내부에 순수 CSS 코드를 작성하는 경우에는 일반 CSS 문법(케밥케이스 및 세미콜론)을 그대로 사용할 수 있습니다.

3) 주석 문법 (HTML 주석 vs JSX 주석)

HTML 주석(<!-- ... -->)을 MDX 문서에 작성하면 MDX 파서가 꺾쇠괄호(<)를 태그 시작으로 오인하여 컴파일 에러를 일으키거나, 빌드 후 본문에 일반 텍스트로 노출됩니다.

{/* ❌ 오류 발생: HTML 주석 사용 금지 */}
<!-- 이 부분은 임시 메모입니다 -->

{/* ✅ 올바른 작성법: 중괄호와 슬래시-별표 조합의 JSX 주석 사용 */}
{/* 이 부분은 임시 메모입니다 */}

4) 중괄호({ })와 자바스크립트 표현식

MDX 본문에서 사용되는 중괄호 {}는 자바스크립트 변수나 표현식을 평가하는 특수 문자로 해석됩니다. 본문에 일반 기호로서의 중괄호를 노출해야 할 때는 이스케이프가 필수입니다.

{/* ❌ 오류 발생: user.name이 정의되지 않은 변수로 평가되어 런타임 크래시 */}
환영합니다, {user.name}님!

{/* ✅ 해결책 1: 역슬래시로 이스케이프 */}
환영합니다, \{user.name\}님!

{/* ✅ 해결책 2: 인라인 코드 백틱(`)으로 감싸기 (가장 권장) */}
JSON 포맷 예시: `{"status": 200, "message": "OK"}`

{/* ✅ 해결책 3: HTML 엔티티 사용 */}
중괄호 표현: &#123;변수명&#125;

5) 꺾쇠괄호(< >) 및 유효하지 않은 태그 이스케이프

비교 연산자(<, >)나 임의의 플레이스홀더 표기(<URL>, <API_KEY>, <world>)를 본문에 그대로 적으면, 파서가 이를 JSX 컴포넌트로 인식하여 닫는 태그를 찾지 못하거나 다음 에러를 발생시킵니다:

에러 메시지: Unexpected character after <, expected a valid JSX tag

{/* ❌ 오류 발생: <endpoint>와 a < b를 태그로 오인 */}
API 요청은 <endpoint> 주소로 보내야 합니다. 응답 시간이 a < b 인지 확인하세요.

{/* ✅ 올바른 작성법: 백틱(`)으로 감싸거나 HTML 엔티티(&lt;, &gt;) 사용 */}
API 요청은 `<endpoint>` 주소로 보내야 합니다. 응답 시간이 a &lt; b 인지 확인하세요.

3. Astro 실무 환경에서 빈발하는 치명적 에러 패턴

MKTG Edge 운영 과정에서 실제로 발생했던 대표적인 빌드 크래시 사례와 예방법입니다.

1) JSX 속성 내부의 원시 줄바꿈(Raw Multi-line Break) 금지 ★★★

오늘 배포 중 발생했던 가장 대표적인 에러 패턴입니다. 컴포넌트 속성(props)에 긴 텍스트를 전달할 때, 큰따옴표("...") 내부에서 키보드 Enter를 쳐서 물리적인 줄바꿈을 포함하면 ECMAScript 구문 규칙상 문자열 리터럴 미종료(Unterminated String Constant) 오류가 발생합니다.

{/* ❌ 빌드 실패: 큰따옴표 내부에 실제 개행(줄바꿈)이 포함됨 */}
<YouTubeEmbed
  url="https://youtu.be/..."
  caption={"첫 번째 줄 설명입니다.
  
  두 번째 줄 설명이 이어집니다."}
/>

{/* ✅ 해결책 1: 줄바꿈 이스케이프 문자(\n) 사용 */}
<YouTubeEmbed
  url="https://youtu.be/..."
  caption={"첫 번째 줄 설명입니다.\n\n두 번째 줄 설명이 이어집니다."}
/>

{/* ✅ 해결책 2: 템플릿 리터럴(백틱 `{` `}`) 활용 */}
<YouTubeEmbed
  url="https://youtu.be/..."
  caption={`첫 번째 줄 설명입니다.

두 번째 줄 설명이 이어집니다.`}
/>

{/* ✅ 해결책 3: 캡션은 한 줄로 간결히 유지 (시맨틱 베스트 프랙티스) */}
<YouTubeEmbed
  url="https://youtu.be/..."
  caption="영상 제목 및 간결한 출처 요약"
/>

2) 마크다운 자동 링크(<https://...>) 문법 충돌

일반 마크다운에서는 URL을 <https://example.com> 형태로 감싸면 하이퍼링크로 자동 변환되지만, MDX에서는 <https:를 JSX 태그명으로 파싱하여 빌드가 즉시 중단됩니다.

  • ❌ 금지: <https://google.com>
  • ✅ 권장: 표준 마크다운 링크인 [Google](https://google.com) 또는 일반 텍스트 URL https://google.com 사용.

3) 컴포넌트 앞뒤 빈 줄(Blank Line) 확보 규칙

MDX 컴포넌트 태그 위아래에는 반드시 **1줄 이상의 빈 줄(Empty Blank Line)**이 존재해야 합니다. 컴포넌트 태그와 일반 마크다운 본문이 빈 줄 없이 맞닿아 있으면, 파서가 마크다운 단락과 JSX 블록의 경계를 구분하지 못해 컴포넌트가 일반 텍스트로 렌더링되거나 파싱 에러가 발생합니다.

{/* ❌ 잘못된 작성: 텍스트와 컴포넌트가 맞닿아 있음 */}
아래 영상을 참고하시기 바랍니다.
<YouTubeEmbed url="..." />
위 영상에서 설명한 바와 같이...

{/* ✅ 올바른 작성: 컴포넌트 전후로 빈 줄 1개씩 확보 */}
아래 영상을 참고하시기 바랍니다.

<YouTubeEmbed url="..." />

위 영상에서 설명한 바와 같이...

4) 특수문자 및 따옴표 충돌

속성값 내부에 큰따옴표가 포함되어 있을 때는 반드시 이스케이프(\")하거나, JSX 표현식 중괄호 안에서 작은따옴표로 감싸야 합니다.

{/* ❌ 오류 발생: 따옴표 중첩으로 구문 깨짐 */}
<YouTubeEmbed title="Google's "New" Feature" />

{/* ✅ 해결책: 이스케이프 또는 템플릿 리터럴 */}
<YouTubeEmbed title='Google의 "새로운" 기능 소개' />
<YouTubeEmbed title={"Google의 \"새로운\" 기능 소개"} />

4. 시맨틱 MDX 컴포넌트 호출 수칙

MKTG Edge에서 제공하는 공식 시맨틱 컴포넌트 사용 시 지켜야 할 규칙입니다:

  1. 컴포넌트 이름은 무조건 PascalCase:
    • 컴포넌트 이름의 첫 글자는 반드시 대문자여야 합니다. (<YouTubeEmbed />, <SoftwareCard />, <SemanticTable />, <Chart />, <GradientCard />)
    • <youtubeEmbed />처럼 소문자로 시작하면 HTML 표준 태그로 간주되어 브라우저에 빈 커스텀 태그로 남게 됩니다.
  2. 자식 요소가 없는 컴포넌트는 단독 닫기(/>):
    • 내용물이 없는 컴포넌트는 <YouTubeEmbed ...></YouTubeEmbed> 대신 <YouTubeEmbed ... />로 간결하게 닫습니다.
  3. 불리언(Boolean) 및 숫자(Number) Props 전달법:
    • 문자열: url="https://..."
    • 불리언: injectSchema={true} 또는 속성명만 단독 선언(injectSchema)
    • 숫자: start={60} (중괄호 사용)

5. 배포 전 사전 검증(Pre-flight) 및 작성 체크리스트

콘텐츠 작성 후 Git 푸시 전 로컬 환경에서 다음 체크리스트를 점검하십시오:

📋 MDX 작성 체크리스트

  • <br />, <img />, <hr /> 등 모든 Void 엘리먼트가 셀프 클로징되어 있는가?
  • HTML 주석(<!-- -->) 대신 JSX 주석({/* */})을 사용했는가?
  • 본문에 단독으로 쓰인 꺾쇠괄호(<, >)가 백틱이나 엔티티로 이스케이프되었는가?
  • 마크다운 자동 링크(<https://...>) 대신 [텍스트](URL) 표준 링크를 사용했는가?
  • 컴포넌트 props의 큰따옴표 안에 키보드 Enter 줄바꿈이 들어가지 않았는가?
  • 커스텀 컴포넌트의 위아래에 빈 줄(Blank line)이 최소 1줄 이상 확보되었는가?
  • 본문의 임의의 중괄호({ })가 인라인 코드(백틱)로 감싸져 있는가?

💻 로컬 빌드 사전 검증 명령어

문서 작성을 마친 후 터미널에서 아래 명령을 실행하여 구문 에러가 없는지 1차 검증합니다:

# 1. Astro 프로젝트 타입 및 구문 검사
npx astro check

# 2. 프로덕션 빌드 사전 실행 (정적 페이지 번들링 검증)
npm run build

빌드가 오류 없이 종료되고 Complete! 메시지가 출력되면 안전하게 배포를 진행할 수 있습니다.