Pandoc: конвертация документов между форматами

Pandoc читает десятки форматов и приводит их к общему внутреннему представлению, а затем собирает выходной файл. Из одного markdown-исходника получаются DOCX для согласования, PDF для печати, EPUB для читалки и HTML для сайта. Разберём установку, базовые преобразования, шаблоны, шрифты, фильтры и пакетную обработку.

Как работает конвертер

В отличие от простых конвертеров, Pandoc разбирает документ в дерево блоков и строк. Заголовки, списки, таблицы и сноски сохраняют смысл, а не превращаются в набор абзацев. Поэтому преобразование Markdown в DOCX даёт настоящие стили Word, а не просто текст.

Обратная сторона — ограничения форматов. Сложная вёрстка, колонтитулы и макросы DOCX в Markdown не переносятся. Pandoc хорошо работает с текстом и структурой, но не заменяет настольную издательскую систему.

Актуальная ветка — 3.x. Проверьте версию и список поддерживаемых форматов, чтобы не искать несуществующие ключи.

pandoc --version
pandoc --list-input-formats | head -30
pandoc --list-output-formats | head -30
pandoc --list-extensions=markdown | head -20

Установка

В Debian и Ubuntu пакет есть в репозитории, но версия может отставать. Для свежей сборки используют официальный установщик или релиз с GitHub. Для PDF нужен движок: XeLaTeX из TeX Live либо Typst, который удобно поставить через cargo.

sudo apt install pandoc texlive-xetex texlive-lang-cyrillic
pandoc --version
cargo install typst-cli
fc-list | grep -i "dejavu" | head

Полный TeX Live занимает несколько гигабайт. Если PDF нужен редко, хватит минимального набора пакетов, а при ошибке LaTeX доустановить отсутствующий пакет по имени из лога.

Базовые преобразования

Ключ -o задаёт выходной файл, -f и -t — входной и выходной форматы. Если формат не указан, Pandoc угадывает его по расширению. Флаг —standalone добавляет полный каркас документа: заголовок, стили, метаданные.

pandoc notes.md -o notes.docx
pandoc report.docx -t markdown -o report.md
pandoc index.html -t markdown -o index.md
pandoc notes.md -s -o notes.html

Для DOCX полезен —reference-doc: файл-образец, из которого берутся стили заголовков, шрифты и поля. Создайте его один раз, поправьте стили в Word или LibreOffice и передавайте при каждой конвертации.

pandoc --print-default-data-file reference.docx > template.docx
pandoc notes.md --reference-doc=template.docx -o notes.docx
pandoc notes.md -o notes.odt

PDF и кириллица

PDF собирается через внешний движок. С XeLaTeX кириллица работает без лишних настроек, если указать шрифт с нужными глифами и язык документа. Переменные -V попадают в шаблон LaTeX.

pandoc notes.md -o notes.pdf --pdf-engine=xelatex \
  -V mainfont="DejaVu Serif" -V lang=ru -V fontsize=11pt
pandoc notes.md -o notes.pdf --pdf-engine=typst

Если PDF не собирается, смотрите последние строки вывода: LaTeX пишет, какого пакета или шрифта не хватает. Частая причина — забытый texlive-lang-cyrillic или шрифт без кириллицы. Для быстрой проверки замените движок на typst: он проще и не требует TeX Live.

Метаданные и шаблоны

Заголовок, автор, дата и язык задаются в YAML-блоке в начале файла. Эти поля подставляются в шаблон и попадают в свойства DOCX и EPUB.

---
title: "Отчёт за квартал"
author: "Отдел документации"
date: 2026-03-01
lang: ru-RU
---

pandoc report.md --metadata title="Отчёт" -o report.pdf

Свой шаблон выводится командой —print-default-template, затем правится и подключается через —template. Для HTML это удобно, когда нужен корпоративный каркас с логотипом и навигацией.

pandoc --print-default-template=html > template.html
pandoc page.md --template=template.html -s -o page.html
pandoc page.md --toc --toc-depth=3 -s -o page.html

Изображения и медиа

При конвертации из DOCX или HTML картинки можно вытащить в отдельный каталог. Ключ —extract-media создаёт папку и переписывает ссылки, иначе изображения потеряются.

pandoc book.docx -t markdown --extract-media=./media -o book.md
find ./media -type f | head
pandoc book.md --resource-path=.:./media -o book.epub

Для EPUB важен порядок: —toc строит оглавление, —metadata задаёт название, а обложка добавляется через —epub-cover-image. Проверьте результат в читалке, а не только в браузере.

pandoc book.md -o book.epub --toc --epub-cover-image=cover.jpg \
  --metadata title="Сборник" --metadata lang=ru
pandoc book.md -t revealjs -s -o slides.html

Слайды и презентации

Из того же Markdown собираются слайды: заголовки второго уровня становятся кадрами, а горизонтальные разделители задают новые слайды. Формат revealjs даёт HTML-презентацию, которая открывается в браузере и не требует PowerPoint. Для офлайн-показа скачайте тему один раз и укажите локальный путь, иначе без сети оформление потеряется.

pandoc talk.md -t revealjs -s -o talk.html \
  -V theme=white -V slideNumber=true
pandoc talk.md -t beamer -o talk.pdf --pdf-engine=xelatex

Beamer собирается через LaTeX и уместен, когда нужен PDF с формулами. Проверьте, что длинные строки кода не выходят за границы слайда: в revealjs помогает класс smaller на секции, в beamer — уменьшенный шрифт.

Фильтры и автоматизация

Lua-фильтры позволяют менять документ на лету: подставлять значения, переименовывать классы, добавлять подписи. Фильтр — обычный файл, который получает элементы дерева.

function Str(el)
  if el.text == "TODO" then
    return pandoc.Emph({pandoc.Str("в работе")})
  end
end

pandoc draft.md --lua-filter=fix.lua -o draft.docx
for f in *.docx; do
  pandoc "$f" -t markdown -o "${f%.docx}.md"
done

Пакетная обработка удобна для архива документов. Добавьте —fail-if-warnings, чтобы скрипт остановился на проблемном файле, и —log=convert.log, чтобы сохранить предупреждения. Для отладки сложных преобразований используйте промежуточный JSON: он показывает, как Pandoc понял исходник.

pandoc report.docx -t json -o report.json
pandoc report.json -t markdown -o report.md
pandoc report.md -o report.docx --fail-if-warnings --log=convert.log

Типичные ошибки

• Пустые таблицы и сноски — проверьте расширения Markdown и не отключайте нужные флаги.
• Кракозябры — укажите кодировку UTF-8 и шрифт с кириллицей.
• Нет картинок — добавьте —resource-path или —extract-media.
• PDF падает — прочитайте лог LaTeX и доустановите пакет.
• Стили DOCX не применились — сверьте имена стилей в reference.docx.

Итог

Pandoc закрывает рутину перевода документов между Markdown, DOCX, PDF, EPUB и HTML. Начните с простой команды и reference.docx, затем добавьте шаблон и фильтры. Держите исходники в Markdown, а форматы собирайте по мере надобности: так текст остаётся версионируемым, а вёрстка — воспроизводимой. Перед пакетной обработкой архива проверьте цепочку на одном тестовом файле.