▲

Markdown이 당신을 가로막고 있다

 (newsletter.bphogan.com)
8P by GN⁺ 2일전 | ★ favorite | 댓글 7개
  • 개발 문서 작성에 널리 쓰이는 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 스타일시트를 통해 다양한 출력 형식으로 변환 가능
    • 대규모 문서 구조 검증과 인덱스 생성에 유리
  • 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은 다운스트림 출력용으로 사용하는 것이 최적임
▲
mstorm 1일전  [-]

요즘 이런류의 글이 많이 보이네요.

텍스트 파일, 마크다운, 더 구조화된 포맷
그렇게 바뀌면서 뭐가 정답이 아니라 적절한 때에 적절한 포맷을 쓰면 됩니다.

그리고 언제나 하나의 파일로 모든 걸 하려고 하면 문제가 생기니 주제에 맞게 분류하고 체계화 하는 것이 필연적이죠.

답변달기
▲
savvykang 1일전  [-]

XML 기반 포맷의 현실과 선택 기준
README나 단발성 문서 등 소규모 문서에는 Markdown이 충분하지만,
대규모·재사용·다채널 문서에는 reStructuredText, AsciiDoc, DocBook, DITA가 더 적합

rst가 XML 기반 포맷인가요? 처음 듣는 소리인데요. 요약이 이상합니다

답변달기
▲
xguru 1일전  [-]

요약상 다른 XML 포맷들과 묶어서 선택기준을 얘기하면서 제목이 그렇게 작성된 것 같네요.
원문에 맞게 수정해놨습니다.

답변달기
▲
jjw9512151 1일전  [-]

Markdown에 필요하면 html 쓰고 거기에 mermaid 붙이면 얼추 되는데.. 그이상은 문서를 위한 문서 일을 위한 일이되는듯

답변달기
▲
ahwjdekf 1일전  [-]

ai 보다 사람이 먼저다. 내가 쓴거 훔쳐가지 마라. 시멘틱 같은소리 하네

답변달기
▲
slowandsnow 1일전  [-]

특별한 문법을 쓰게 된다면 또 다른 학습 곡선, 전용 파싱 도구, 뷰어, 에디터 등등 전부 원활하게 지원해야 가능.. 저 정도면 그냥 대부분의 ai 서비스와 원활하게 연결 가능한 구글 독스나 노션 쓰는 게 나을지도

답변달기
▲
GN⁺ 2일전  [-]
Hacker News 의견

  • Markdown의 핵심은 다른 언어에는 없는 광범위한 지원성임
    대부분의 대안들은 별도의 툴이 필요하고, Markdown이 이미 지원되는 환경에서는 쓸 수 없음
    Google Docs조차 숨겨진 기능으로 Markdown 붙여넣기를 지원함
    완벽하지 않아도 “어디서나 쓸 수 있음”이 장점임
    HTML이 SGML보다 단순했지만 브라우저가 지원하면서 표준이 된 것처럼, Markdown도 시간이 지나며 발전할 수 있음
    표준화의 모호함, 기능 부족, 호환성 문제 등은 HTML4 시절과 비슷한 상황임
    완전히 대체하기보다는 점진적 진화가 더 현실적인 길이라 생각함

    • Markdown의 또 다른 장점은 누구나 5분 만에 배울 수 있음
      예전에 신문사 기자들에게 도입했는데, 하루 만에 MS Word보다 편하다고 느꼈음
      복잡한 서식 없이 입력한 그대로 결과가 나오는 점이 매력적이었음
      기술 비전문가도 쉽게 익히는 포맷임
    • Markdown은 이미 사실상 승리자라고 생각함
      클라이언트가 Word나 PDF를 원하면 그렇게 보내지만, 결국 수신자가 포맷을 정함
      코드 블록은 백틱으로 충분하고, 복잡한 표나 다이어그램은 HTML로 보완 가능함
    • Markdown의 중요한 특성은 평문으로도 읽기 쉬움
      LaTeX나 HTML보다 훨씬 가독성이 좋음
      고수준 마크업 언어로서 HTML로 컴파일된다고 생각함
      필요하면 HTML을 직접 섞어 쓸 수도 있음
    • Markdown이 널리 쓰이는 건 사실이지만, 다른 언어를 막는 기술적 이유는 없음
      다만 사회적 요인으로 인해 확장이 더딤
      HTML처럼 체계적인 문법이 없어 확장하기 어려움
      이미 수많은 Markdown 방언이 존재하지만 대부분 소수 도구에만 국한됨
      CommonMark가 그나마 표준에 가까움
      확장 시스템을 도입하더라도 문법 충돌 문제로 성공 가능성은 낮다고 봄
    • Markdown이 발전할 가능성은 있지만, 중앙 권위가 없음
      CommonMark가 있지만 이는 규범이 아닌 기술적 설명 수준임

  • Markdown은 어디서든 HTML 태그를 포함할 수 있음
    공식 문서에서도 명시되어 있음
    그래서 저자가 말한 제약은 실제로 존재하지 않음

    • HTML을 넣을 수 있다는 건 모두 아는 사실임
      하지만 Markdown을 쓰는 이유는 HTML을 직접 치지 않기 위해서임
      <p>나 <a> 같은 태그를 계속 써야 한다면 Markdown을 쓸 이유가 없음
      결국 “HTML을 쓰면 된다”는 답이라면 Markdown의 존재 이유가 사라짐
    • 실제로는 HTML과 Markdown을 자유롭게 섞을 수 없음
      HTML 블록이 들어가면 Markdown 문법이 비활성화됨
      AsciiDoc은 이 부분에서 훨씬 유연함
    • 나도 Pandoc과 Markdown을 쓰지만 AsciiDoc이나 LaTeX로 돌아갈 생각은 없음
      각주나 목차도 대부분 지원되고, 일반 텍스트 기반 작업에는 충분함
      수식이나 버튼 같은 건 필요하지 않음
    • Reddit이나 GitHub처럼 보안상 HTML을 막는 플랫폼도 있음
      신뢰되지 않은 사용자가 HTML을 쓰면 위험하기 때문임
    • 나는 Markdown 문서에 인터랙티브 요소를 넣기도 함
      지금은 콘텐츠 작성용으로만 Markdown을 사용 중임

  • 대학 시절 물리학 전공 때 LaTeX로 논문을 썼음
    화학과는 Word를 썼는데, 분야별로 표준이 다름
    TeX의 버전은 목표 완성도를 π 값에 근접하게 표현함
    현재 버전은 3.141592653으로, 47년간 안정적으로 유지됨
    TeX 위키, Pi 버전 설명 참고
    CLI 도구에는 manpage 포맷도 유용함

    • 학부 때 LaTeX로 문서 작성을 배웠지만, 지금은 Typst를 더 추천함
      LaTeX의 후계자로 가장 유망하다고 생각함
    • 문서 작성은 마찰이 적어야 함
      LaTeX는 진입 장벽이 높고, 문서보다는 조판용 포맷이라 비효율적임
      문서는 외형보다 내용 중심이어야 함
    • 나는 유일하게 Word로 논문을 썼음
      LaTeX 폰트를 쓰고 PDF 버그를 수정하느라 고생했지만 괜찮았음
      연구에 따르면 LaTeX 사용자는 더 많은 시간을 들이지만 과정의 만족도는 높음
      “만드는 재미를 즐기는 사람들”의 도구 같음

  • Markdown은 최소 기능 제품(MVP) 같은 존재임
    배우기 쉽고, 렌더링되지 않아도 읽기 쉬움
    PDF 제작은 AsciiDoc에서 Typst로 옮겼는데, 접근성 문제를 해결해줌
    하지만 어떤 마크업 언어도 글의 품질을 대신 높여주진 않음
    펜을 바꾼다고 글이 좋아지는 건 아님

    • 작성자는 두 가지 용도를 혼동했다고 봄
      Markdown은 빠르게 콘텐츠를 만드는 사람을 위한 것임
      구조적 완성도를 추구하는 사람에게는 맞지 않음
      두 목적을 모두 만족시키는 언어는 없을 것 같음
    • Djot이라는 Markdown 대안도 흥미로움
      GitHub 링크 참고
    • LaTeX는 문단마다 주석을 달게 해서 글을 더 깊이 생각하게 함
    • Typst가 흥미로워 보이지만, 현재는 웹 에디터와 VSCode 플러그인만 있어 생태계가 제한적임

  • 이 글의 논조는 “Markdown이 LLM 발전을 막는다”는 주장임
    하지만 의미론적 풍부함을 자동으로 얻을 수 있다는 전제가 비현실적임
    팀 내에서는 그런 작업을 할 시간도 없고, Markdown으로 충분함
    시맨틱 웹 논의처럼, 결국 누가 데이터를 관리하느냐의 문제임

  • 나는 블로그를 Org-mode + Emacs로 씀
    코드 블록을 연결해 문서 안에서 실행할 수 있는 기능이 특히 마음에 듦
    Blorgit, lazyblorg 같은 플랫폼도 써봤지만 설정이 번거로워 직접 HTML로 내보내고 rsync로 서버에 올림
    Ruby 스크립트로 인덱스를 붙여 배포함
    Markdown보다 훨씬 표현력이 풍부하고 자연스러움

    • Org-mode가 Emacs에 묶여 있지 않았다면 기본 포맷이 되었을 것 같음
    • Ox-Hugo를 써봤는지 묻고 싶음
      Org 파일을 Hugo 블로그로 내보내는 훌륭한 시스템임
    • Org-mode는 Emacs에 너무 밀착되어 있어 이식이 어려움
      LSP가 생기면 다른 환경에서도 쓸 수 있을 것 같음

  • “Markdown은 구조가 부족하다”는 주장에 부분적으로 동의하지만, 이분법적 접근이 아쉬움
    포맷을 선택하기 전에 필요한 구조를 먼저 이해했어야 함
    그래서 약간 불쾌하면서도 동의하기 어려움

  • DITA를 Markdown 대안으로 제시한 건 완전히 엇나간 주장임
    DITA는 대규모 기업용 XML 시스템으로, Markdown과는 목적이 전혀 다름
    5천 명 이상, 다국어 제품 라인 같은 환경에서만 적합함
    Markdown을 쓰는 상황이라면 DITA는 절대 맞지 않음
    둘 다 시간 낭비임

    • DITA를 몰랐는데, “Markdown이 복잡하다면 XML을 써라”는 말이 너무 웃겼음
    • DITA와 그 툴체인 실패 사례를 더 듣고 싶음

  • Markdown을 10년 넘게 써왔는데 여전히 잘 작동함
    글의 주장도 완전히 틀리진 않지만, Markdown 사용자들이 느끼는 문제는 아님
    필요하면 다른 걸 쓰면 됨
    그래도 제목이 좋아서 5분 정도 읽어봤음

  • MyST를 Markdown의 한 형태로 언급하고, 다시 reStructuredText(rST)를 예로 든 게 이상함
    MyST의 목적이 바로 rST의 대체제임
    문법은 Markdown스럽지만, 구조적 의미와 directive, role 등을 모두 지원함
    Sphinx 이슈에서도 관련 논의가 있음

답변달기