Markdown победил мир почти случайно. Он был достаточно простым, чтобы его полюбили блогеры и разработчики, и достаточно удобным, чтобы стать де-факто стандартом GitHub-документации. Но теперь, когда технический контент стал куда масштабнее простых README, выяснилось неприятное: Markdown — самый слабый фундамент для серьёзной документации.
И дело не в том, что “не хватает синтаксиса”. Проблема в том, что Markdown не мыслит семантикой.
Он не понимает разницы между шагом в инструкции, концепцией, предупреждением или параметром API.
Для человека это не критично. Для машин — фатально.
И это превращает Markdown из удобного инструмента в своеобразный «технический JavaScript 2005 года»: прост, вездесущ, но ограничивает вас, как только попытаться построить что-то серьёзное.
🔧 Markdown — это “неявная типизация” документации
Брайан Хоган очень чётко провёл аналогию: Markdown — это язык с неявной типизацией.
📌 Пишется быстро.
📌 Проверок нет.
📌 Стандарта нет — лишь каноническая договорённость.
По сути:
- 🟪 Один и тот же синтаксис в одном месте означает “шаг инструкции”,
- 🟪 в другом — “важная концепция”,
- 🟪 а где-то — просто “ещё один пункт списка”.
И ни один инструмент, ни один LLM, ни один IDE-плагин не сможет угадать ваш смысл — Markdown просто не оставляет зацепок.
Эта неоднозначность критична, если:
- контент должен жить в большом проекте
- документы синдицируются между платформами
- контент должен читаться LLM-агентами
- документация обязана быть машинопонятной
- нужна консистентность словаря и терминологии
Markdown не гарантирует ничего из этого — он буквально “форматирование без структуры”.
🧩 Фрагментация Markdown: CommonMark, GFM, MyST, MultiMarkdown, MDX
Мало того, что Markdown лишён схемы — его вообще нет как единого языка.
- CommonMark не поддерживает часть синтаксиса GitHub
- MyST добавляет научные элементы, но ломает совместимость
- MDX — вообще смесь React-компонентов и Markdown
- MultiMarkdown позволяет то, что другие движки игнорируют
И получается типичная проблема:
👉 «Документация работает НА МОЁМ РЕНДЕРЕРЕ».
С точки зрения переносимости контента это катастрофа.
Самый яркий пример — MDX:
# Install
<Command>npm install my-library</Command>
Стильно? Да.
Семантично? Да.
Переносимо? Полностью нет.
Это не Markdown — это React.
Попробуйте экспортировать этот текст в Confluence, Docusaurus или PDF — всё развалится.
По сути MDX — это признание поражения Markdown.
Люди начинают вшивать семантику поверх Markdown, потому что Markdown не способен её выразить.
🧠 Почему семантическая разметка — не роскошь, а инженерная необходимость
Семантика — это не “красивые теги”.
Это масштабируемость и машиночитаемость.
Семантика помогает:
- 📚 переиспользовать контент (целые блоки, шаги, определения)
- 🌐 транслировать в PDF, ePub, HTML, Docx, man pages
- 📖 строить глоссарии и индекс терминов
- 🤖 подавать LLM-моделям структурированную информацию
- 🏗️ строить строгие пайплайны документации
- 🔍 обеспечивать консистентность терминов
- 🔄 переходить между системами без переработки контента
Markdown этого просто не умеет. Он не знает понятий <step>, <note>, <cmd>, <param> — ничего.
И здесь появляются альтернативы, которые действительно работают.
💡 Что использовать вместо Markdown: краткий обзор идеальных кандидатов
🌿 reStructuredText (RST)
Язык экосистемы Python / Sphinx.
Сохраняет читаемость, но добавляет роли, директивы и связи.
Пример:
.. note::
This library requires NodeJS ≥ 22.
.. code-block:: bash
npm install my-library
Отлично подходит для API-мануалов, туториалов, больших руководств.
📘 AsciiDoc
Невероятно выразителен и удобен для больших проектов.
Особенности:
- атрибуты (:revnumber:)
- инклюды
- условная логика
- кросс-ссылки
- встроенные “NOTE”, “WARNING”, “TIP”
AsciiDoc — идеальная ступень между Markdown и XML-монстрами.
🏗️ DocBook (XML)
Корпоративный стандарт промышленной документации.
Строгая схема (XSD), строгие теги. По сути — XHTML, но для документации.
<command>npm install my-library</command>
<note>This library requires NodeJS ≥ 22</note>
Да, XML громоздок — но он единственный даёт полную семантику.
🧬 DITA (Darwin Information Typing Architecture)
Ракета корпоративной техдока.
Модульность, переиспользование, фильтрация, конрефы, специализация.
Теги вроде:
- <task>
- <concept>
- <step>
- <cmd>
- <note>
DITA — это уже не «формат документации», а система управления знаниями.
🔍 Моё мнение: Markdown хорош там, где нужно быстро — не там, где нужно правильно
Markdown — это быстрый черновик, но плохой источник истины.
Если ваш проект:
- 🌱 маленький — Markdown ок
- 🔧 средний — AsciiDoc или RST лучше
- 🏭 корпоративный — DocBook / DITA без вариантов
Мой личный опыт показывает:
как только команда пытается добавить в Markdown:
- собственные компоненты
- плагины
- нестандартные блоки
- условную логику
- включения файлов
- расширенную семантику
…всё мгновенно превращается в неуниверсальную самодельную систему, которую потом невозможно экспортировать или поддерживать.
Парадокс в том, что любой крупный проект в итоге «изобретает» свой псевдо-DocBook поверх Markdown.
Так почему бы не начать сразу с нормального формата?
🔗 Источники
1️⃣ Оригинальная статья: https://newsletter.bphogan.com/archive/issue-45-markdown-is-holding-you-back/