Готовили релиз нашего нового решения для 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 хранится все, что касается преобразования из одного формата в другой.
А вот какой результат получился:
Получилось достаточно надежно и гибко. Мы сами можем управлять что включать в PDF-документацию из Markdown и какими стилями пользоваться при преобразовании из markdown в pdf.
А как вы решаете подобные задачи с документацией?
Если статья показалась вам интересной и полезной, то буду благодарен за подписку на мой Телеграм-канал Код ИТ-директора, где я описываю случаи из своей жизни и публикую полезный контент по ИТ.
