Markdown — популярный и удобный язык разметки, но это также и очень ограниченный формат. Поэтому задача написания в Markdown сложной технической документации по ГОСТ, научной статьи с автоматической настройкой оформления для заданного издательства или хорошо оформленного онлайн-учебника может показаться неосуществимой. В этой статье рассмотрим способ работы над научно-техническими статьями и книгами в формате Markdown на основе подхода Docs as Code с учётом строгих ограничений на оформление, используемый @true-grue и мной при подготовке учебных материалов в РТУ МИРЭА.
Способ заключается в применении утилиты pandoc для построения дерева абстрактного синтаксиса (AST) Markdown-документа с последующим переписыванием AST набором фильтров на Lua и трансляцией AST в форматы docx и pdf, соответствующие ГОСТ, а также в диалект markdown, совместимый с mdBook, для генерации онлайн-учебника.
Онлайн-версии книг, написанных с использованием описанного подхода, и репозитории с исходным кодом книг опубликованы на GitHub и GitHub Pages: книга по конфигурационному управлению, книга по разработке кроссплатформенных программмных систем.