MDX 사용 정책

이 문서는 문서를 .md로 작성할지 .mdx로 작성할지 판단하는 기준을 운영 관점에서 정리합니다. 단순히 “가능하다/불가능하다”가 아니라, 장기 유지보수 비용과 편집 일관성을 함께 고려해 선택할 수 있도록 구성했습니다. 팀 문서 품질을 안정적으로 유지하려면 파일 형식 선택 기준을 사전에 명확히 고정해야 합니다.

기본 원칙

운영 문서는 .md를 기본으로 사용하고, .mdx는 반드시 필요한 경우에만 선택합니다. 기본 형식을 단순하게 유지해야 작성자 교체, 리뷰, 배포 검증 과정에서 예외 처리가 줄어듭니다.

• 기본값: .md
• 예외값: .mdx (컴포넌트 직접 렌더링 필요 시)

현재 MDX 문서

현재 운영 기준에서 MDX는 랜딩 페이지 1건으로 제한해 사용합니다. 문서 전반을 MDX로 확장하지 않는 이유는 편집 일관성과 유지보수 안정성을 우선하기 때문입니다.

• docs/
  • src/
    • content/
      • docs/
        • index.mdx

MDX를 선택해야 하는 경우

아래 조건을 충족하면 .mdx를 선택합니다. 공통 특징은 “순수 마크다운만으로 구현하기 어려운 UI/컴포넌트 표현이 필요한 경우”입니다.

선택 기준

• 페이지에서 컴포넌트를 직접 import/render 해야 할 때
• 마크다운만으로 구현하기 어려운 복합 레이아웃이 필요한 때
• 랜딩/쇼케이스처럼 시각 구성 비중이 높은 페이지를 만들 때

MDX 선택 예시 구조

• docs/
  • src/
    • content/
      • docs/
        • landing-custom/
          • index.mdx

MDX를 피해야 하는 경우

아래 유형은 .md가 더 적합합니다. 문서 목적이 정보 전달 중심이라면 MDX 도입 이점보다 유지보수 비용이 더 커질 가능성이 높습니다.

회피 기준

• 단순 텍스트/이미지/표/코드 예시 문서
• 체크리스트, 절차, 운영 로그 중심 문서
• 장기 운영 문서(편집 일관성과 인수인계가 중요한 문서)

MD 권장 예시 구조

• docs/
  • src/
    • content/
      • docs/
        • markdown-guide/
          • elements/
            • index.md

의사결정 절차

형식 선택은 “기능 필요성 → 유지보수 영향 → 팀 편집성” 순서로 판단합니다. 아래 절차를 문서 생성 전에 확인하면 불필요한 MDX 확장을 방지할 수 있습니다.

1. 마크다운으로 구현 가능한지 먼저 검토
2. 컴포넌트 import가 꼭 필요한지 판단
3. 장기 유지보수 비용(리뷰/수정/인수인계)을 평가
4. 필요 시에만 .mdx 선택

검토 체크리스트

• 이 문서가 컴포넌트 렌더링을 반드시 요구하는가?
• 순수 마크다운으로 대체 가능한가?
• MDX를 선택했을 때 팀 편집 난이도가 증가하는가?
• 장기 운영 문서라면 .md로 전환 가능한가?
• 최종 선택 사유를 문서 생성 시점에 기록했는가?