Привет! TLDR

Пару месяцев назад я решала проблему — чем генерить документацию в PDF, если у тебя доку собирает MkDocs, который из коробки этого не умеет. Просила тут помощи и обещала здесь же отписаться, что пробовала, к какому решению пришла. Я начинающий автоматизатор, могу написать простенький скрипт на баше или питоне, не больше. В сторону генерации из HTML я сразу не пошла, так как там не одностраничный документ и CSS для меня это слишком сложно. Поэтому я смотрела конвертеры из Markdown в PDF.

Что я пробовала:

1. Конвертер https://hub.docker.com/r/fiware/md2pdf/. Мне с разбега даже hello world не дался, нужно разбираться в настройках. Если бы не помог @glu0n, я бы может и не справилась. Результат очень не очень внешне + не работает с кириллицей из коробки. Зато не нужно собирать всё в один файл, он это делает за вас, ему можно скормить тот же конфиг что уже есть в MkDocs.

2. Typora https://typora.io/. Самое простое и быстрое решение. Делает все через Pandoc, очень хорошо настроен шаблон, PDF получается эстетичный, правильно подсвечивает код. Можно скачать десктопное приложение. Cобственно я так и сделала, когда мне нужно было сделать PDF быстро. Минусы: все равно кое-чего не хватает например, в готовом PDF нет номеров страниц, нужно как-то собирать все md-файлы в один, ну и герерить придется руками (зато GUI).

3. Foliant https://github.com/foliant-docs. Самый серьезный инструмент, делает всё, что нужно. Тоже генерит через Pandoc. Тоже не нужно собирать ему один файл. Разобраться самостоятельно можно, есть документация, хотя мне все-таки потребовалась помощь создателей, но они слава богу отвечают в чате. Из коробки PDF у меня получился достаточно приличного качества. Но стало понятно, что если я хочу что-то поправить, то нужно будет самой настраивать шаблон, плюс Foliant по-моему нет смысла использовать только для сборки PDF, он не использует ваш конфиг MkDocs, использует свой конфиг с содержанием (foliant.yml). По-хорошему нужно делать сборку всех форматов доки Фолиантом.

4. Pandoc. Полный контроль над процессом, но настройка, самое сложное — LaTeX-шаблон. Ну и собирать все md-файлы в один тоже придется. Килограммы документации, и она неплохая.

Как я генерирую PDF в итоге:

Стало понятно что все равно придется настраивать LaTeX-шаблон. И надо склеить md-файлы в один. Так как я контрол-фрик, да и сборка html-документации в MkDocs у меня уже настроена, я не стала склеивать файлы сторонней тулзой. Я написала короткий Python-скрипт, который парсит YAML-конфиг MkDocs и собирает один md-файл. Этот один я скармливаю Pandoc. Использую --pdf-engine=xelatex. Обложку с названием документа дизайнер сделал в PDF и я ее приклеиваю в конце с помощью pdfunite. Осталось разобраться в туче параметров tex-шаблонов.