- 開発ドキュメント作成で広く使われる 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 は ダウンストリーム出力用 として使うのが最適である
7件のコメント
rstはXMLベースのフォーマットなんですか？ 初めて聞きましたが。要約がおかしいです
要約を見る限り、他のXMLフォーマットとまとめて選定基準について述べているので、そのようなタイトルになっていたようですね。
原文に合わせて修正しておきました。
必要なら Markdown に HTML を書いて、そこに mermaid を貼ればだいたい何とかなるけど……それ以上になると、文書のための文書作業、作業のための作業になってしまう気がする
AIより人間が先だ。私が書いたものを盗むな。セマンティックとかふざけたことを言うな
特別な文法を使うことになるなら、別の学習コストに加えて、専用のパーサー、ビューア、エディタなど、すべてが円滑に対応して初めて成り立つ……。あの程度なら、むしろたいていのAIサービスとスムーズに連携できる Google Docs や Notion を使うほうがいいのかもしれない
Hacker Newsの意見
Markdownの核心は、他の言語にはない幅広いサポートにある ほとんどの代替手段は別途ツールが必要で、Markdownがすでにサポートされている環境では使えない Google Docsでさえ隠し機能としてMarkdownの貼り付けをサポートしている 完璧でなくても、「どこでも使える」ことが利点だ HTMLがSGMLより単純だったが、ブラウザが対応したことで標準になったように、Markdownも時間とともに発展しうる 標準化の曖昧さ、機能不足、互換性の問題などはHTML4時代と似た状況だ 完全に置き換えるよりも、段階的な進化のほうが現実的な道だと思う
MarkdownにはどこでもHTMLタグを含められる 公式ドキュメントにも明記されている だから著者が述べた制約は実際には存在しない
やのようなタグをずっと書き続けるなら、Markdownを使う理由がない 結局「HTMLを使えばいい」という答えなら、Markdownの存在意義が消える大学時代、物理学専攻でLaTeXで論文を書いていた 化学科はWordを使っていて、分野ごとに標準が違う TeXのバージョンは、目標完成度をπの値に近づける形で表している 現在のバージョンは3.141592653で、47年間安定して維持されている TeX Wiki、Piバージョンの説明 参照 CLIツールにはmanpage形式も有用だ
Markdownは**最小機能製品(MVP)**のような存在だ 学びやすく、レンダリングされなくても読みやすい PDF作成はAsciiDocからTypstに移行したが、アクセシビリティの問題を解決してくれる しかし、どんなマークアップ言語でも文章の質そのものを高めてはくれない ペンを替えても文章が良くなるわけではない
この記事の論調は、「MarkdownがLLMの発展を妨げる」という主張だ しかし、意味論的な豊かさを自動的に得られるという前提は非現実的だ チーム内ではそんな作業をする時間もなく、Markdownで十分だ セマンティックWebの議論と同様、結局は誰がデータを管理するかの問題だ
自分はブログをOrg-mode + Emacsで書いている コードブロックをつないで文書内で実行できる機能がとくに気に入っている Blorgit、lazyblorg のようなプラットフォームも使ったが、設定が面倒で、自分でHTMLに書き出してrsyncでサーバーに上げている Rubyスクリプトでインデックスを付けて配布している Markdownよりはるかに表現力が豊かで自然だ
「Markdownは構造が不足している」という主張には部分的に同意するが、二項対立的なアプローチが惜しい フォーマットを選ぶ前に、必要な構造を先に理解すべきだった だから少し不快でもあり、同意しにくい
DITAをMarkdown代替として提示したのは完全に的外れな主張だ DITAは大規模企業向けのXMLシステムで、Markdownとは目的がまったく違う 5,000人以上、多言語の製品ラインのような環境でのみ適している Markdownを使う状況なら、DITAは決して合わない どちらも時間の無駄だ
Markdownを10年以上使ってきたが、今でも十分うまく動いている 記事の主張もまったくの間違いではないが、Markdownユーザーが感じる問題ではない 必要なら別のものを使えばいい それでもタイトルが良かったので5分ほど読んでみた
MySTをMarkdownの一形態として挙げ、そのうえで再びreStructuredText(rST)を例に出したのは奇妙だ MySTの目的は、まさにrSTの代替であることだ 構文はMarkdown風だが、構造的意味やdirective、roleなどをすべてサポートしている Sphinxのissueでも関連する議論がある
最近はこういう類いの文章をよく見かけますね。
テキストファイル、Markdown、より構造化されたフォーマット。
そうやって変わっていく中で、何かが正解というわけではなく、適切なときに適切なフォーマットを使えばいいのです。
そして、いつも1つのファイルですべてをやろうとすると問題が生じるので、テーマに合わせて分類し、体系化していくことが必然的ですね.