Markdown is holding you back
Markdown популярен за читаемость и простоту, но для серьёзной технической документации его ограничения критичны: он не описывает структуру контента семантически, генерируя лишь базовый подмножество HTML-тегов. Поисковики, LLM, IDE и AI-агенты нуждаются в явной семантике для индексации и ответов на вопросы разработчиков. Markdown — как implicit typing в JS: гибкий, без схемы и гарантий consistency. Заголовок в одном файле может быть концепцией, в другом — шагом, без машинно-читаемого различия. Разные flavors (CommonMark, GitHub-Flavored, MyST, MultiMarkdown) несовместимы: footnotes работают не везде, code blocks требуют разной разметки.
MDX расширяет Markdown компонентами вроде <Command>npm install my-library</Command>, стандартизируя отображение, но это не портативно — контент ломается при синдикации. Семантическая разметка (как <section>, <article> в HTML5) описывает суть контента, а не вид, enabling трансформацию и reuse в HTML, PDF, ePub или другие форматы без потерь.