Автоматическая сборка PDF-документации из Markdown в GitLab CI

Готовили релиз нашего нового решения для 1С по отправке СМС-подтверждений и столкнулись с классической задачей. Документацию мы ведем в Markdown. Это удобно для нас, но не для конечного клиента.

Клиенту нужен привычный PDF. Простой и надежный.

Главный вопрос: как автоматически собирать несколько .md файлов с картинками в один PDF-файл прямо в пайплайне GitLab CI? Особенно когда твои раннеры работают на PowerShell под Windows, как у нас.

Решение нашлось в связке Docker и Pandoc. Вот пошаговый план:

• Основа: Берем готовый Docker-образ с Pandoc.

• Подготовка: Внутрь контейнера копируем нашу папку docs с Markdown-файлами.

• Сборка: Запускаем Pandoc, который конвертирует все файлы в единый PDF.

• Выгрузка: Копируем готовый PDF из контейнера и сохраняем его как артефакт в GitLab.

Подход универсален, неважно, где запущен Docker. Вся логика инкапсулирована в контейнере.

Готовый pipeline лежит здесь:

• Pipeline: https://github.com/Diversus23/actions/blob/main/yml/extension.yml (смотрите этап «Создание документации»)

• Dockerfile: https://github.com/Diversus23/actions/blob/main/yml/docker/Dockerfile.build

• Pandoc.yml: https://github.com/Diversus23/actions/blob/main/yml/docs/pandoc.yml

А вот как это выглядит на скришотах:

Обратите внимание на настройку с pandoc.yml

В pandoc.yml хранится все, что касается преобразования из одного формата в другой. А так же в какой последовательности необходимо объединять файлы markdown. На скриншоте выше видно, что сначала будет включен файл README.md, а затем 01-intro.md

А вот какой результат получился:

Получилось достаточно надежно и гибко. Мы сами можем управлять что включать в PDF-документацию из Markdown и какими стилями пользоваться при преобразовании из markdown в pdf.

А как вы решаете подобные задачи с документацией?

Если статья показалась вам интересной и полезной, то буду благодарен за подписку на мой Телеграм-канал Код ИТ-директора, где я описываю случаи из своей жизни и публикую полезный контент по ИТ.