- 개발 문서 작성에 널리 쓰이는 Markdown은 단순성과 접근성 덕분에 인기가 높지만, 구조적 표현력 부족으로 인해 대규모 기술 문서에는 한계가 있음
- Markdown은 암묵적 타입 시스템처럼 작동해 일관성이나 스키마 검증이 불가능하며, 다양한 Markdown 변형(flavor) 간 호환성 문제도 존재
- MDX 등 확장 문법은 표현력을 높이지만, 시스템 간 이식성과 표준화 부족으로 오히려 복잡성을 증가시킴
- reStructuredText, AsciiDoc, DocBook, DITA 등은 명시적 구조와 의미론적 마크업(semantic markup) 을 제공해 재사용성과 기계 해석성을 강화함
- 소규모 문서에는 Markdown이 충분하지만, 대규모·다채널 문서 관리에는 구조화된 포맷으로의 전환이 필요함
Markdown의 구조적 한계
- Markdown은 사람이 읽기 쉬운 단순 문법으로 GitHub나 정적 사이트에서 보기 좋은 문서를 만들 수 있음
- 그러나 콘텐츠의 의미를 기술하지 못해 기계가 이해할 수 있는 구조 정보가 부족함
- 검색엔진, LLM, IDE, AI 에이전트 등은 문서의 의미론적 구조를 활용하지만, Markdown은 제한된 HTML 태그만 생성
- Markdown은 플랫폼별 문법 차이로 인해 재사용이나 콘텐츠 통합 시 비일관성 문제 발생
- 결과적으로 Markdown은 최소공통분모 수준의 포맷으로, 복잡한 문서 관리에는 부적합
Markdown의 암묵적 타입 문제
- Markdown은 명시적 스키마나 타입 정의가 없는 포맷으로, 동일한 제목이나 리스트가 문맥에 따라 다른 의미를 가질 수 있음
- 다양한 Markdown 변형(flavor)들이 존재해, 도구 간 렌더링 차이가 발생
- 예: 어떤 도구는 각주를 지원하지만, 다른 도구는 무시함
- MDX는 React 컴포넌트를 삽입해 표현력을 확장하지만, 시스템 간 호환성 문제로 이식성이 떨어짐
- 이러한 확장은 Markdown의 한계를 보완하려는 시도지만, 표준화되지 않은 임시방편적 해결책에 불과함
의미론적 마크업의 중요성
- 의미론적 마크업은 콘텐츠의 형태가 아닌 의미를 기술함
- 예: “단계(step)”와 “리스트 항목”은 시각적으로 같아도 의미는 다름
- HTML5는
<section>,<article>,<aside>등 의미 기반 태그를 도입해 구조적 표현을 강화 - 의미론적 마크업의 핵심 이점
- 변환과 재사용: 동일한 콘텐츠를 HTML, PDF, ePub 등 다양한 형식으로 변환 가능
- 기계 해석성: LLM이나 에이전트가 구조를 명확히 인식해 더 정확한 응답 제공
- Markdown은 이러한 구조 정보를 제공하지 못해, 후처리나 변환 시 정보 손실이 발생
대안 포맷 비교
-
reStructuredText
- Python 생태계의 Sphinx에서 사용되는 포맷으로, 지시문(directive) 과 역할(role) 을 통해 구조적 의미를 표현
- 코드 블록, 주석(note), 교차 참조(:ref:) 등 명시적 구조 요소 지원
- 대규모 기술 문서에 적합하며 HTML 및 PDF 생성 지원
-
AsciiDoc
- 속성(attribute) 과 조건부 콘텐츠, 포함(include) 기능을 제공하는 의미론적 텍스트 포맷
-
NOTE,WARNING같은 주의문과 UI 요소, 단축키 표기 등 기술 문서에 특화된 표현 지원 - AsciiDoctor를 통해 HTML, PDF, ePub, DocBook 등으로 변환 가능
-
DocBook (XML)
-
기술 출판용 XML 기반 모델로,
<command>,<note>,<xref>등 의미 있는 태그 체계 제공 - 용어집, 색인, UI 요소, 함수 이름 등 전문 문서에 필요한 태그 포함
- XSLT 스타일시트를 통해 다양한 출력 형식으로 변환 가능
- 대규모 문서 구조 검증과 인덱스 생성에 유리
-
기술 출판용 XML 기반 모델로,
-
DITA (Darwin Information Typing Architecture)
- 기업용 기술 문서 표준으로 쓰이는 모듈식 XML 기반 구조
-
주제 기반 XML 아키텍처로,
<task>,<step>등 절차적 구조를 명확히 정의 - 콘텐츠 재사용(conref), 필터링, 다채널 출판 등 기업용 문서 관리 표준으로 활용
- DITA Open Toolkit을 통해 렌더링과 변환 자동화 지원
XML이 불편해 보여도 필요한 이유
- Markdown은 가볍지만 구조·표준·일관성이 결여된 임시 해법
- Markdown에 MDX·플러그인·커스텀 스크립트로 복잡도를 더하고 있다면,
구조화된 포맷을 아예 채택하는 것이 장기적으로 더 안정적
그럼 어떻게 해야할까?
- README나 단발성 문서 등 소규모 문서에는 Markdown이 충분하지만,
대규모·재사용·다채널 문서에는 reStructuredText, AsciiDoc, DocBook, DITA가 더 적합 - 기획 문서·개발자 문서·재사용·대규모 관리가 필요하면 reST/AsciiDoc → DocBook/DITA 순으로 고려
- 가장 풍부한 구조를 가진 포맷을 소스로 사용하고, 필요 시 Markdown으로 변환하는 접근이 바람직함
- Markdown은 출력용 포맷으로는 유용하지만, 원본(source of truth) 으로 사용하면 구조적 확장이 어려움
- 원본은 의미 구조가 풍부한 포맷에 두고, Markdown은 다운스트림 출력용으로 사용하는 것이 최적임