마크다운, 대규모 기술 문서 작성에는 부적합...시맨틱 마크업 형식 대안 주목

개발자 문서 작성에 널리 쓰이는 마크다운이 시맨틱 구조 부재로 한계 드러내

[한국정보기술신문] 개발자 커뮤니티에서 표준처럼 사용되는 마크다운(Markdown)이 대규모 기술 문서 작성 환경에서 한계를 드러내고 있다. 전문가들은 구조적 문서화가 필요한 프로젝트에서 보다 풍부한 시맨틱 마크업 형식으로의 전환을 권고하고 있다.

기술 저술가 브라이언 호건은 최근 자신의 뉴스레터를 통해 마크다운의 근본적 한계를 지적했다. 그는 마크다운이 인간이 읽기 쉽고 접근하기 쉬운 장점이 있지만, 내용의 의미를 기계가 이해할 수 있는 형태로 설명하지 못한다고 밝혔다.

마크다운의 기본 문법은 HTML이 제공하는 시맨틱 태그 중 극히 일부만 활용한다. 이는 검색 엔진 인덱싱, 대형 언어 모델(LLM) 파싱, IDE 통합 등 기계가 문서를 처리하는 과정에서 맥락 정보가 손실되는 결과를 낳는다.

일관성 부재와 이식성 문제

마크다운은 표준 명세가 없어 여러 변종이 존재한다. GitHub Flavored Markdown, CommonMark, Pandoc Markdown, MultiMarkdown 등 각기 다른 기능과 마크업을 지원하며, 한 도구에서 작동하는 코드가 다른 환경에서는 렌더링되지 않는 경우가 빈번하다.

일부에서는 MDX와 같은 확장을 통해 마크다운의 한계를 보완하려 하지만, 이는 커스텀 컴포넌트에 의존하게 돼 다른 시스템으로의 콘텐츠 이식이 어려워진다. 호건은 MDX가 사실상 시맨틱 마크업을 재발명하는 것이지만 표준화되지 않고 이식성이 없는 방식이라고 비판했다.

시맨틱 마크업의 중요성

시맨틱 마크업은 콘텐츠가 어떻게 보여야 하는지가 아니라 무엇인지를 설명한다. 예를 들어 단순히 글머리 기호가 있는 텍스트라고 표현하는 대신, 절차의 단계라고 명시하는 것이다. 사람에게는 비슷해 보일 수 있지만, 기계나 퍼블리싱 파이프라인에게는 완전히 다른 의미다.

이는 두 가지 중요한 이유로 중요하다. 첫째, 콘텐츠를 다른 형식으로 변환할 때 추측 없이 정확한 변환이 가능하다. 둘째, 기계가 문서를 더 정확하게 처리할 수 있다. 명시적인 시맨틱 태그는 모호함을 제거한다.

대안 마크업 형식들

호건은 마크다운을 대체할 수 있는 네 가지 형식을 제안했다.

먼저 reStructuredText는 파이썬 생태계의 일반 텍스트 마크업 언어로, 지시문과 역할, 구조적 시맨틱을 지원한다. Sphinx 문서 생성 도구의 기반 형식으로 사용되며, 코드 블록, 주석, 교차 참조 등을 명시적으로 표현할 수 있다.

AsciiDoc은 인간이 읽기 쉬우면서도 시맨틱 표현력이 풍부하다. 문서 메타데이터를 위한 속성, 조건부 콘텐츠, 포함 메커니즘 등을 제공한다. AsciiDoctor를 통해 HTML, PDF, ePub, DocBook 등 다양한 형식으로 변환할 수 있다.

DocBook은 기술 출판을 위해 설계된 XML 기반 문서 모델이다. 계층적이고 시맨틱한 구조를 태그와 속성으로 표현하며, 산업 수준의 변환을 가능하게 한다. 함수명, 변수, 애플리케이션명, 키보드 단축키, UI 요소 등을 위한 사전 정의된 태그를 제공한다.

DITA는 콘텐츠 작성, 관리, 출판을 위한 표준으로, 주제 기반 XML 아키텍처에 재사용과 전문화 기능이 내장돼 있다. 절차적 구조를 위한 태그와 단계를 명확히 정의하며, 단일 문서에서 여러 버전을 생성하는 콘텐츠 필터링 기능을 제공한다.

선택 기준과 전환 전략

호건은 빠른 README 파일이나 단기 문서에는 마크다운이 적합하지만, 구조가 필요한 개발자 문서 사이트에는 reStructuredText나 AsciiDoc이, 대규모 문서 세트에는 DocBook이나 DITA가 더 나은 선택이라고 조언했다.

핵심은 관리 가능한 가장 풍부한 형식에서 시작해 하향 내보내기하는 것이다. 마크다운은 개발자에게 친숙하고 접근하기 쉬운 훌륭한 출력 형식이지만, 원본 소스로 고정하면 나중에 맥락을 추가하기 어렵다는 점을 유념해야 한다.

업계 전문가들은 문서화 전략을 수립할 때 장기적인 유지보수성과 확장성을 고려해야 하며, 프로젝트 규모와 요구사항에 맞는 적절한 마크업 형식을 선택하는 것이 중요하다고 강조하고 있다.

한국정보기술신문 정보기술분과 김지원 기자 news@kitpa.org