Pandoc

Pandoc — это свободная кроссплатформенная утилита командной строки для конвертации документов из одного формата разметки в другой. Разрабатывается Джоном Макфарлейном (John MacFarlane) и сообществом. Pandoc рассматривается как «швейцарский нож» для работы с текстовыми форматами, поддерживая десятки входных и выходных форматов, включая Markdown, LaTeX, HTML, EPUB, DOCX, PDF, MediaWiki, reStructuredText, AsciiDoc и другие.

История

Проект был начат Джоном Макфарлейном, профессором философии Калифорнийского университета в Беркли, в 2006 году. Первоначальной целью было создание инструмента для конвертации между Haskell-версией Markdown и другими форматами, используемыми в академической среде. Первый публичный релиз (версия 0.1) состоялся в августе 2006 года.

Ключевые вехи развития:

• 2007: добавлена поддержка LaTeX и HTML.
• 2009: реализована поддержка EPUB и DocBook.
• 2011: Pandoc становится частью многих дистрибутивов Linux (Debian, Ubuntu, Fedora).
• 2014: версия 1.13 вводит поддержку собственного формата Markdown (Pandoc’s Markdown) с расширениями.
• 2017: версия 2.0 — кардинальная переработка архитектуры: введение абстрактного синтаксического дерева (AST) и Lua-фильтров.
• 2020: версия 2.10 — улучшенная поддержка JATS, TEI и других научных форматов.
• 2023: версия 3.1 — значительное расширение возможностей Lua-скриптинга и поддержка новых форматов, таких как Typst.

На 2025 год Pandoc остаётся активно развивающимся проектом с регулярными релизами.

Архитектура и принцип работы

Pandoc построен на функциональном языке программирования Haskell. Основной принцип работы — преобразование документа через внутреннее представление (абстрактное синтаксическое дерево, AST). Процесс состоит из трёх этапов:

1. Парсинг (чтение) — входной документ разбирается в AST.
2. Трансформация (опционально) — AST может быть модифицировано с помощью фильтров (на Lua или Python) или встроенных преобразований.
3. Генерация (запись) — AST преобразуется в целевой выходной формат.

Этот подход позволяет:

• Обрабатывать документы независимо от исходного формата.
• Применять единые правила трансформации (например, замену изображений, изменение стилей) ко всем форматам.
• Легко добавлять поддержку новых форматов — достаточно написать парсер и генератор для AST.

Поддерживаемые форматы

Pandoc поддерживает более 30 входных и более 40 выходных форматов. Ниже приведены основные.

Входные форматы

Выходные форматы

Ключевые возможности

Расширения Markdown

Pandoc реализует собственный вариант Markdown (Pandoc’s Markdown), который включает множество расширений, отсутствующих в стандартном CommonMark:

• Таблицы: несколько типов (pipe, grid, multiline, simple).
• Сноски: обычные и концевые.
• Математические формулы: поддержка LaTeX-математики (встроенной и выносной).
• Перекрёстные ссылки: на заголовки, таблицы, рисунки, формулы.
• Библиография: интеграция с BibTeX, BibLaTeX, CSL (Citation Style Language).
• Фильтры: возможность обработки AST на Lua или Python.
• Метаданные: YAML-блок в начале документа для указания заголовка, автора, даты, тегов.
• Вставка кода: с подсветкой синтаксиса (поддерживаются сотни языков).
• Диаграммы: поддержка Mermaid, Graphviz, PlantUML (через фильтры).
• Внутренние ссылки: на заголовки, сноски, разделы.
• Списки: нумерованные, маркированные, вложенные, с разными стилями маркеров.
• Изображения и видео: встраивание с подписями.
• Специальные символы: тире, кавычки, многоточие.

Фильтры и скрипты

Фильтры — это программы, которые модифицируют AST документа до его генерации. Pandoc поддерживает два основных типа:

• Lua-фильтры: встроенная поддержка, выполняются на интерпретаторе Lua. Примеры: изменение заголовков, замена изображений, добавление примечаний.
• Python-фильтры: через библиотеку pandocfilters или panflute. Позволяют использовать Python для сложных преобразований.

Фильтры могут быть написаны на любом языке, поддерживающем JSON-ввод/вывод (например, Haskell, JavaScript, Ruby).

Библиография и цитирование

Pandoc имеет встроенную поддержку управления библиографией:

• Поддерживает форматы: BibTeX, BibLaTeX, CSL JSON, CSL YAML, RIS, EndNote, Zotero.
• Использует CSL (Citation Style Language) для оформления цитирования в любом стиле (APA, MLA, Chicago, ГОСТ и др.).
• Автоматически генерирует список литературы в конце документа.
• Поддерживает перекрёстные ссылки на цитаты.

Шаблоны и темы

Pandoc использует шаблоны на языке Haskell для генерации выходных документов. Пользователь может:

• Использовать встроенные шаблоны (для HTML, LaTeX, EPUB, DOCX).
• Создавать собственные шаблоны на основе переменных (например, $title$, $author$, $body$).
• Применять темы для HTML-презентаций (reveal.js, beamer).
• Настраивать стили для DOCX через reference-документ.

Применение

Pandoc используется в различных сферах:

Академическая среда

• Написание научных статей в Markdown с последующей конвертацией в LaTeX/PDF.
• Создание диссертаций и отчётов с автоматической библиографией.
• Подготовка презентаций для конференций (Beamer, reveal.js).
• Конвертация учебных материалов из одного формата в другой.

Техническая документация

• Написание документации в Markdown с последующей публикацией в HTML, PDF, EPUB.
• Интеграция с системами контроля версий (Git).
• Генерация документации для API (например, из OpenAPI-спецификаций).
• Создание электронных книг (EPUB) для технических руководств.

Издательское дело

• Подготовка рукописей для издательств (конвертация из DOCX в LaTeX или JATS).
• Создание книг в форматах EPUB, PDF, MOBI.
• Автоматизация вёрстки через шаблоны.

Веб-разработка

• Генерация статических сайтов (например, с помощью Jekyll, Hugo, Pelican).
• Конвертация Markdown в HTML для блогов и CMS.
• Создание HTML-презентаций.

Личное использование

• Ведение заметок в Markdown с возможностью экспорта в PDF или DOCX.
• Создание резюме и портфолио.
• Конвертация электронных книг между форматами.

Примеры использования

Базовая конвертация

```bash

Конвертация Markdown в HTML

pandoc input.md -o output.html

Конвертация Markdown в DOCX

pandoc input.md -o output.docx

Конвертация LaTeX в EPUB

pandoc input.tex -o output.epub ```

Конвертация с библиографией

``bash pandoc article.md --bibliography refs.bib --csl apa.csl -o article.pdf ``

Использование фильтра

``bash pandoc input.md --lua-filter=filter.lua -o output.html ``

Создание презентации

``bash pandoc slides.md -t revealjs -o slides.html ``

Ограничения

Несмотря на широкие возможности, Pandoc имеет некоторые ограничения:

• Сложность настройки: для продвинутого использования требуется знание шаблонов, Lua-скриптинга и форматов.
• Качество конвертации: при преобразовании между сложными форматами (например, DOCX → LaTeX) возможны потери форматирования, особенно для сложных таблиц, встроенных объектов, макросов.
• Отсутствие графического интерфейса: Pandoc — исключительно консольная утилита, что может быть неудобно для начинающих пользователей.
• Зависимость от внешних инструментов: для генерации PDF требуется установленный LaTeX-дистрибутив (например, TeX Live) или wkhtmltopdf.
• Поддержка кириллицы: в некоторых форматах (например, PDF через LaTeX) требуется настройка кодировки и шрифтов.

Связанные проекты

• Pandoc-crossref: фильтр для автоматической нумерации и перекрёстных ссылок на рисунки, таблицы, формулы.
• Pandoc-citeproc: устаревший фильтр для цитирования (встроен в Pandoc начиная с версии 2.11).
• PanWriter: графический интерфейс для Pandoc.
• Markdown Preview Enhanced: плагин для VS Code, использующий Pandoc.
• Pandocomatic: инструмент для автоматизации конвертации документов с использованием конфигурационных файлов.
• Quarto: система научной публикации, основанная на Pandoc.

Источники

• MacFarlane, J. Pandoc: a universal document converter. Официальная документация.
• Pandoc User’s Guide. Версия 3.1, 2023.
• Репозиторий проекта на GitHub: jgm/pandoc.
• «Pandoc: The Swiss Army Knife of Document Conversion» — статья на сайте Linux Journal, 2015.
• «Pandoc: A Universal Document Converter for the Command Line» — обзор на сайте Opensource.com, 2020.