Книга в Markdown: Автоматическая сборка статического сайта mdBook и файла DOCX с оформлением по ГОСТ

Текст книг, учебных пособий, научно-технических статей, документации, дипломных и курсовых работ часто набирается и редактируется в WYSIWYG-редакторе, таком как Microsoft Word, в том числе вследствие того, что издательства и организации требуют от авторов оформленный по ГОСТ или внутренним стандартам docx-документ. Процесс работы в Microsoft Word и аналогичных редакторах не лишён недостатков: docx-файлы трудно версионировать в git, а для объединения нескольких документов в один придётся перенумеровывать источники, рисунки, таблицы, формулы.

Альтернативой docx является LaTeX. Однако работа со стилями в LaTeX простотой и минималистичным синтаксисом не отличается, причём издательства от использования формата docx отказываться не торопятся. А инструменты в духе typst отличаются нестандартным синтаксисом языка для описания документов, причём возможность генерации сайтов в typst имеет пометку «in preview».

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

Способ заключается в применении утилиты pandoc для построения дерева абстрактного синтаксиса (AST) Markdown-документа с последующим переписыванием AST набором фильтров на Lua и трансляцией AST в форматы docx и pdf, соответствующие ГОСТ, а также в диалект markdown, совместимый с mdBook, для генерации онлайн-учебника в виде статического сайта. Исходный код книги, написанной с использованием описанного в статье подхода, опубликован на GitHub.