빠른 흐름
Markdown 이동 전 점검
1. 대상 렌더러가 CommonMark, GFM, MDX 중 무엇을 지원하는지 확인
2. 표, task list, footnote, Mermaid, math 사용 여부 확인
3. raw HTML과 custom component 지원 여부 확인
4. heading anchor와 상대 링크를 실제 렌더링에서 확인
5. PDF/Word 변환이면 이미지, 표, 코드 블록을 별도 점검이동 경계
Markdown은 파일 확장자가 같아도 렌더링 규칙이 다를 수 있다
.md 파일이라고 해서 모든 환경에서 같은 결과가 나오지는 않는다. CommonMark만 지원하는 렌더러, GFM 확장을 지원하는 GitHub, JSX까지 컴파일하는 MDX, PDF 변환 도구는 각각 문법 경계가 다르다. 문서를 옮길 때는 파일 확장자보다 "어떤 parser와 plugin이 처리하는가"를 먼저 확인해야 한다.
GitHub 전용 기능은 이동 전에 목록화한다
GitHub에서 쓰던 문서에는 task list, autolink, footnote, alert, Mermaid, 상대 링크 변환 같은 기능이 섞여 있을 수 있다. 이 중 일부는 GFM spec에 포함되고 일부는 GitHub 서비스 후처리나 별도 렌더러 기능에 가깝다. 사내 위키나 정적 사이트로 옮길 때는 이 기능들이 그대로 렌더링되는지 샘플 페이지로 확인해야 한다.
GitHub 문서 이동 전 검색
- "[!NOTE]"
- "```mermaid"
- "[^"
- "- [ ]"
- "<details>"
- "<img"MDX로 옮기면 Markdown 문자가 JavaScript 경계가 될 수 있다
MDX는 Markdown에 JSX와 JavaScript expression을 섞기 때문에 {}, <Component>, import 같은 문자가 문서 컴파일에 영향을 준다. 일반 Markdown에서는 그냥 텍스트였던 예시가 MDX에서는 expression이나 JSX로 해석될 수 있다. JSON, template, angle bracket 예시는 fenced code block 안에 두는 편이 안전하다.
PDF와 Word 변환은 화면 렌더링과 다른 실패 지점이 있다
웹에서는 잘 보이는 넓은 표, 긴 코드 라인, 외부 이미지, Mermaid diagram이 PDF나 Word 변환에서는 잘리거나 이미지로 고정될 수 있다. 인쇄나 배포용 문서는 화면 미리보기만 보지 말고 실제 export 결과를 확인해야 한다. 특히 표는 모바일과 인쇄에서 모두 깨지기 쉬우므로 짧은 데이터에만 쓰는 편이 안정적이다.
점검 기준
| 이동 대상 | 먼저 볼 것 |
|---|---|
| GitHub README -> 정적 사이트 | GFM plugin, anchor 생성 규칙 |
| Markdown -> MDX | JSX tag, {} expression, import 경계 |
| Markdown -> PDF/Word | 표 폭, 이미지 경로, 코드 줄바꿈 |
| 사내 위키 | raw HTML, footnote, Mermaid 지원 여부 |
| 여러 저장소 재사용 | 상대 링크와 이미지 경로 |
공식 참고: CommonMark Spec, GitHub Flavored Markdown Spec, MDX
주의할 점
Markdown 문서는 원본보다 렌더링 결과가 계약입니다. 대상 플랫폼이 바뀌면 표, 링크, HTML, diagram, MDX expression이 다르게 해석될 수 있으므로 대표 문서 한두 개를 먼저 렌더링해 보고 규칙을 확정해야 합니다.
실패 예시
- README에서 잘 보이던 Mermaid, alert, task list를 그대로 PDF 문서로 변환함
- 결과: diagram은 누락되고 alert는 blockquote 텍스트로 보이며 표가 페이지 밖으로 넘침
- 대응: export 대상별로 지원 문법을 줄이고, 복잡한 시각 자료는 이미지와 대체 설명을 함께 제공한다참고 링크
3 sources