Документация без боли или создаём технические шедевры с Pandoc и PlantUML

Вы когда-нибудь тратили часы на оформление документации, а потом получали комментарий: «Нужно доработать и немного оформление поменять»? Или, ещё хуже, «А где диаграмма?» — и понимали, что рисовать её вручную в Word — это как пытаться построить ракету с помощью зубочисток и скотча (цензурная версия).

Не думаю, что открою большую тайну, но видя, как мучаются коллеги, хочу поделиться проверенным способом. Как с помощью Markdown, PlantUML и Pandoc превратить создание сложной технической документации (на самом деле любой) в прозрачный технологичный процесс («Документация как код»), а не в бесконечную рутину и трату времени. В конце статьи ссылка на готовый репозиторий, который можно сразу адаптировать под свои проекты.

---

Что бы будем использовать?

Markdown — чистая текстовая разметка

Markdown — это формат разметки, намного проще html, позволяет писать форматированный текст. Для освоения достаточно 10-минутного руководства. Преимущества Markdown:

• Хранение в Git как обычный текстовый документ

• Совместное редактирование без неразрешимых конфликтов

• Отсутствие скрытой невидимой разметки (в отличие от Word)

Pandoc — универсальный конвертер документов

Pandoc — это утилита командной строки, переводящая файлы из одного формата в другой. Он поддерживает Markdown, HTML, DOCX, PDF, LaTeX и множество других стандартов. Работает полностью offline и поддерживает подключение внешних файлов стилей и шаблонов. Преимущества Pandoc:

• Один источник текста — генерация множества форматов на выходе

• Поддержка шаблонов стилей для точного соблюдения корпоративного бренда

• Автоматизация сборки документации в CI/CD пайплайнах (если очень хочется)

PlantUML — диаграммы, как код

PlantUML позволяет описывать схемы и диаграммы текстовым языком. Пишете понятный код — получаете графическую диаграмму любой сложности. Преимущества PlantUML:

• Версионирование в Git вместе с текстом документации

• Высокая скорость правок — не нужно перерисовывать схемы вручную при изменении архитектуры

• Нативная интеграция с Pandoc через фильтры сборки

YAML — блок метаданных

YAML-блок (frontmatter) размещается в самом начале Markdown-файла и задает глобальные свойства документа: заголовок, автора, дату, версию, а также параметры генерации оглавления (TOC).

Пошаговый алгоритм работы

Шаг 1. Установка Pandoc и зависимостей: Установите Pandoc, а также Java и Graphviz (dot), которые необходимы для оффлайн-рендеринга диаграмм PlantUML.

Шаг 2. Настройка шаблона оформления DOCX (custom-reference.docx): Сгенерируйте базовый файл стилей Word и настройте шрифты, отступы и заголовки.

Шаг 3. Настройка фирменных стилей PlantUML (если у вас есть диаграммы конечно): Задайте стили диаграмм прямо в коде (skinparam) или подключите единый файл корпоративного стиля (!include).

Шаг 4. Создание Markdown-файла с YAML-заголовком: Сформируйте ваш документ .md, добавив в начало блок YAML-метаданных.

Шаг 5. Внедрение PlantUML-диаграмм в текст: Опишите схемы непосредственно в теле Markdown-документа с помощью блоков @startuml … @enduml.

Шаг 6. Сборка итогового документа одной командой: Запустите Pandoc с указанием файла стилей и фильтров для автоматической генерации DOCX, PDF или HTML.

Структура исходного Markdown-документа (Пример)

Ниже приведён пример целостного файла document.md, сочетающего YAML-метаданные, основной текст и встроенный блок PlantUML:

---title: "Техническая документация проекта X"author: "Алексей К."date: "2026-09-13"# Настройки языка и оглавленияlang: ru                  # Критически важно для переносов и кириллицыtoc: true                 # Включить оглавлениеtoc-depth: 2              # Глубина оглавления (1 и 2 уровни)toc-title: "Оглавление"   # Переопределяем стандартное "Содержание" или "Table of Contents"---# 1. ВведениеВ данном документе описана архитектура системы X.# 2. Архитектурная схемаНиже представлена диаграмма взаимодействия компонентов:```plantuml@startumlskinparam monochrome trueskinparam shadowing falseactor Пользовательnode "Веб-сервер" as Webdatabase "База данных" as DBПользователь -> Web: HTTP-запросWeb -> DB: SQL-запросDB --> Web: Ответ с даннымиWeb --> Пользователь: HTML-страница@enduml```

Настройка стилей PlantUML

Для того чтобы диаграммы выдерживались в едином стиле, используйте директивы стилизации или темы:

Вариант A: Локальная настройка в коде диаграммы

@startumlskinparam monochrome trueskinparam shadowing false@enduml

Вариант B: Подключение централизованного файла корпоративного стиля

@startuml!include styles/corporate-style-v1.puml@enduml

Настройка стиля Word (custom-reference.docx)

Pandoc позволяет подключить шаблон custom-reference.docx, который задаёт оформление всех элементов (заголовков, списков, таблиц и кода).

1. Создание базового файла стилей при помощи pandoc:

pandoc -o custom-reference.docx --print-default-data-file reference.docx

2. Редактирование стилей: Откройте полученный файл в Microsoft Word. Вызовите меню управления стилями с помощью комбинации клавиш Alt + Ctrl + Shift + S. Настройте шрифты, цвета, интервалы для стилей Heading 1, Heading 2, Normal, Table Grid и сохраните файл.

Конвертация в Pandoc

Для сборки итогового документа DOCX со стилями и автоматическим рендерингом PlantUML используйте следующую команду:

pandoc --filter pandoc-plantuml --reference-doc=custom-reference.docx --toc my-doc.md -o my-doc.docx

Если не требуется диаграммы:

pandoc --reference-doc=custom-reference.docx --toc my-doc.md -o my-doc.docx

Описание настройки Pandoc для конвертации PlantUML-диаграмм есть в официальной документации.

Параметры команды:

• –filter pandoc-plantuml (или —lua-filter plantuml.lua) — автоматически компилирует блоки PlantUML в изображения при сборке.

• –reference-doc=custom-reference.docx — указывает на ваш файл стилей Word.

• –toc — автоматическое формирование оглавления.

• -o my-doc.docx — целевой выходной файл.

Команды для генерации других форматов:

# Сборка в PDF (требуется pdfEngine, например xelatex)pandoc --filter pandoc-plantuml --toc my-doc.md -o my-doc.pdf# Сборка в HTML-страницуpandoc --filter pandoc-plantuml --toc --standalone my-doc.md -o my-doc.html

Готовый шаблон проекта

Все описанные настройки собраны в репозитории на GitFlic.ru:

• Пример MD-файла со встроенными диаграммами PlantUML

• Готовый шаблон custom-reference.docx для стилизации

• Готовый шаблон style.pump

• Cкрипт build.ps1 для сборки в DOCX, PDF и HTML

Надеюсь Markdown + Pandoc + PlantUML + YAML помогут вам превратить рутину по оформлению в прозрачную разработку: версионируемую, воспроизводимую и эстетичную.

Попробуйте один раз — и ручная верстка в Word останется в прошлом!