# Markdown이 당신을 가로막고 있다 > Clean Markdown view of GeekNews topic #24560. Use the original source for factual precision when an external source URL is present. ## Metadata - GeekNews HTML: [https://news.hada.io/topic?id=24560](https://news.hada.io/topic?id=24560) - GeekNews Markdown: [https://news.hada.io/topic/24560.md](https://news.hada.io/topic/24560.md) - Type: GN+ - Author: [neo](https://news.hada.io/@neo) - Published: 2025-11-24T04:33:28+09:00 - Updated: 2025-11-24T04:33:28+09:00 - Original source: [newsletter.bphogan.com](https://newsletter.bphogan.com/archive/issue-45-markdown-is-holding-you-back/) - Points: 10 - Comments: 7 ## Summary 개발자 문서의 기본 언어처럼 쓰이는 **Markdown**이 사실상 **구조적 표현력의 한계**에 부딪히고 있다는 지적입니다. 단순한 문법 덕분에 빠르게 작성할 수 있지만, **의미론적 마크업**이 부족해 LLM·검색엔진·자동화 도구가 문서를 제대로 해석하기 어렵습니다. 이에 비해 **reStructuredText**, **AsciiDoc**, **DocBook**, **DITA** 같은 포맷은 명시적 구조와 스키마 검증을 지원해 **대규모·다채널 문서 관리**에 훨씬 유리합니다. 문서가 점점 코드처럼 다뤄지는 시대, “가벼움”보다 “구조”를 선택할 시점이라는 메시지가 인상적입니다. ## Topic Body - 개발 문서 작성에 널리 쓰이는 **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은 **다운스트림 출력용**으로 사용하는 것이 최적임 ## Comments ### Comment 46736 - Author: savvykang - Created: 2025-11-24T17:38:31+09:00 - Points: 1 > XML 기반 포맷의 현실과 선택 기준 > README나 단발성 문서 등 소규모 문서에는 Markdown이 충분하지만, 대규모·재사용·다채널 문서에는 reStructuredText, AsciiDoc, DocBook, DITA가 더 적합 rst가 XML 기반 포맷인가요? 처음 듣는 소리인데요. 요약이 이상합니다 ### Comment 46737 - Author: xguru - Created: 2025-11-24T19:40:50+09:00 - Points: 1 - Parent comment: 46736 - Depth: 1 요약상 다른 XML 포맷들과 묶어서 선택기준을 얘기하면서 제목이 그렇게 작성된 것 같네요. 원문에 맞게 수정해놨습니다. ### Comment 46735 - Author: jjw9512151 - Created: 2025-11-24T16:18:19+09:00 - Points: 1 Markdown에 필요하면 html 쓰고 거기에 mermaid 붙이면 얼추 되는데.. 그이상은 문서를 위한 문서 일을 위한 일이되는듯 ### Comment 46731 - Author: mstorm - Created: 2025-11-24T15:30:06+09:00 - Points: 2 요즘 이런류의 글이 많이 보이네요. 텍스트 파일, 마크다운, 더 구조화된 포맷 그렇게 바뀌면서 뭐가 정답이 아니라 적절한 때에 적절한 포맷을 쓰면 됩니다. 그리고 언제나 하나의 파일로 모든 걸 하려고 하면 문제가 생기니 주제에 맞게 분류하고 체계화 하는 것이 필연적이죠. ### Comment 46730 - Author: ahwjdekf - Created: 2025-11-24T15:29:09+09:00 - Points: 1 ai 보다 사람이 먼저다. 내가 쓴거 훔쳐가지 마라. 시멘틱 같은소리 하네 ### Comment 46725 - Author: slowandsnow - Created: 2025-11-24T13:06:15+09:00 - Points: 1 특별한 문법을 쓰게 된다면 또 다른 학습 곡선, 전용 파싱 도구, 뷰어, 에디터 등등 전부 원활하게 지원해야 가능.. 저 정도면 그냥 대부분의 ai 서비스와 원활하게 연결 가능한 구글 독스나 노션 쓰는 게 나을지도 ### Comment 46707 - Author: neo - Created: 2025-11-24T04:33:29+09:00 - Points: 1 ###### [Hacker News 의견](https://news.ycombinator.com/item?id=46017782) - 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 태그를 포함할 수 있음 [공식 문서](https://daringfireball.net/projects/markdown/syntax#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 위키](https://en.wikipedia.org/wiki/TeX), [Pi 버전 설명](https://www.preethamrn.com/posts/piver) 참고 CLI 도구에는 manpage 포맷도 유용함 - 학부 때 LaTeX로 문서 작성을 배웠지만, 지금은 **Typst**를 더 추천함 LaTeX의 후계자로 가장 유망하다고 생각함 - 문서 작성은 **마찰이 적어야 함** LaTeX는 진입 장벽이 높고, 문서보다는 조판용 포맷이라 비효율적임 문서는 외형보다 내용 중심이어야 함 - 나는 유일하게 Word로 논문을 썼음 LaTeX 폰트를 쓰고 PDF 버그를 수정하느라 고생했지만 괜찮았음 연구에 따르면 LaTeX 사용자는 더 많은 시간을 들이지만 **과정의 만족도**는 높음 “만드는 재미를 즐기는 사람들”의 도구 같음 - Markdown은 **최소 기능 제품(MVP)** 같은 존재임 배우기 쉽고, 렌더링되지 않아도 읽기 쉬움 PDF 제작은 AsciiDoc에서 Typst로 옮겼는데, 접근성 문제를 해결해줌 하지만 어떤 마크업 언어도 글의 품질을 대신 높여주진 않음 펜을 바꾼다고 글이 좋아지는 건 아님 - 작성자는 두 가지 용도를 혼동했다고 봄 Markdown은 빠르게 콘텐츠를 만드는 사람을 위한 것임 구조적 완성도를 추구하는 사람에게는 맞지 않음 두 목적을 모두 만족시키는 언어는 없을 것 같음 - **Djot**이라는 Markdown 대안도 흥미로움 [GitHub 링크](https://github.com/jgm/djot#rationale) 참고 - LaTeX는 문단마다 주석을 달게 해서 **글을 더 깊이 생각하게 함** - Typst가 흥미로워 보이지만, 현재는 웹 에디터와 VSCode 플러그인만 있어 **생태계가 제한적**임 - 이 글의 논조는 “Markdown이 **LLM 발전을 막는다**”는 주장임 하지만 의미론적 풍부함을 자동으로 얻을 수 있다는 전제가 비현실적임 팀 내에서는 그런 작업을 할 시간도 없고, Markdown으로 충분함 **시맨틱 웹** 논의처럼, 결국 누가 데이터를 관리하느냐의 문제임 - 나는 블로그를 **Org-mode + Emacs**로 씀 코드 블록을 연결해 문서 안에서 실행할 수 있는 기능이 특히 마음에 듦 [Blorgit](https://orgmode.org/worg/blorgit.html), [lazyblorg](https://karl-voit.at/tags/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 이슈](https://github.com/sphinx-doc/sphinx/issues/8039)에서도 관련 논의가 있음