Pandoc преобразует Markdown, HTML, DOCX, ODT, EPUB, LaTeX, reStructuredText и десятки других форматов, собирает PDF через выбранный движок, оформляет библиографии, формулы, таблицы и подсветку кода, а также применяет шаблоны, файлы настроек и Lua-фильтры для повторяемой публикации документов.

Работа строится вокруг одной команды: пользователь указывает исходный файл, при необходимости задаёт входной и выходной форматы, добавляет параметры и получает новый документ. Отдельного окна с панелями нет: интерфейсом служит терминал, поэтому все действия видны в команде, легко повторяются и переносятся в сценарии автоматизации. Для первой конвертации достаточно конструкции pandoc input.md -o output.docx, а сложный издательский процесс можно свести к одному файлу YAML с десятками заранее проверенных опций.

Главная особенность Pandoc — преобразование структуры, а не попытка копировать каждый пиксель исходной страницы. Заголовки, абзацы, списки, ссылки, сноски, формулы, цитаты и таблицы проходят через внутреннее представление документа, после чего записываются средствами целевого формата. Такой подход особенно полезен для технической документации, учебных материалов, отчётов, книг и сайтов, но требует заранее выбрать, какие элементы должны сохраниться семантически, а какие будут оформляться стилями DOCX, CSS, LaTeX, Typst или другого выходного средства.

Как устроен интерфейс Pandoc

После запуска команды Pandoc не открывает мастер импорта и не предлагает выбирать профиль мышью. Терминал сразу становится журналом операции: в первой строке остаётся введённая команда, ниже появляются предупреждения или сообщение об ошибке, а успешная конвертация обычно завершается без лишнего текста. Поэтому проверка результата состоит из двух шагов: убедиться, что процесс вернул код завершения 0, и открыть созданный файл в программе, которая понимает целевой формат. Для автоматизации это удобнее, чем диалоговые окна: сценарий может прервать сборку при ненулевом коде, сохранить стандартный поток ошибок и не ждать действий пользователя.

Команда pandoc --version показывает версию, включённые возможности, движок Lua и путь к пользовательскому каталогу данных. pandoc --help выводит краткую справку по параметрам, а длинные перечни форматов и расширений удобнее получать отдельными командами. В работе полезно сначала проверить --list-input-formats, --list-output-formats и --list-extensions=markdown, потому что поддержка чтения и записи у форматов несимметрична: наличие writer не означает наличие reader и наоборот.

Параметры можно писать в полном или коротком виде. Например, -f markdown равно --from=markdown, -t html5 равно --to=html5, а -o report.html задаёт выходной файл. Полные имена лучше читаются в файлах настроек и CI-конфигурациях, короткие удобны при разовой работе. Опции обрабатываются слева направо; значения из файла defaults можно переопределить последующими аргументами командной строки, что позволяет держать общий профиль и менять только имя результата или один параметр конкретной сборки.

Базовый рабочий процесс

Самый надёжный сценарий начинается с простой пары один исходный файл — один результат. Создайте файл note.md, поместите в него заголовок, несколько абзацев и список, затем выполните pandoc note.md -o note.docx. Расширение выходного файла позволяет Pandoc выбрать writer автоматически. Для текстового результата можно не указывать -o: тогда данные будут отправлены в стандартный вывод, и их можно просмотреть в терминале или передать следующей программе через канал.

Когда расширение неоднозначно или файл не имеет расширения, формат задают явно. Команда pandoc source.txt -f markdown -t html5 -o page.html не полагается на догадку по имени. Это особенно важно для файлов .txt, XML-подобных форматов и Markdown с нестандартным набором расширений. Входных файлов может быть несколько: Pandoc читает их в указанном порядке и объединяет в один документ. Метаданные и заголовки при этом следует планировать заранее, иначе несколько верхнеуровневых заголовков превратятся в последовательные разделы одного результата.

Для диагностики удобно сначала выводить в простой текст или собственное native-представление. Если список или таблица уже неверно распознаны на этапе чтения, смена шаблона PDF не исправит структуру. Если native-дерево корректно, а DOCX оформлен не так, проблема находится на стороне writer, reference.docx или конкретного просмотрщика. Такое разделение экономит время: Pandoc состоит из reader, внутреннего AST и writer, и каждый этап можно проверять отдельно.

Чтение и запись форматов

Pandoc умеет читать распространённые варианты Markdown, HTML, LaTeX, reStructuredText, Textile, Org, DocBook, JATS, MediaWiki, DokuWiki, TWiki, Jira-разметку, Emacs Muse, OPML, Haddock и ряд других текстовых форматов. К двоичным входным форматам относятся DOCX, ODT, EPUB, RTF, электронные блокноты Jupyter и некоторые табличные или презентационные контейнеры, когда для них предусмотрен reader. Список следует получать из установленного экземпляра, потому что набор зависит от сборки и развивается.

Выходные writer охватывают HTML5, XHTML, Markdown разных диалектов, LaTeX, ConTeXt, Typst, DocBook, JATS, TEI, RTF, ODT, DOCX, EPUB, презентации PowerPoint, несколько форматов слайдов на HTML, man-страницы, plain text и форматы документации для редакторов и систем разработки. PDF занимает особое место: Pandoc сначала формирует промежуточный документ, а затем вызывает внешний движок. Из-за этого одинаковый Markdown может дать заметно разный PDF при использовании LaTeX, Typst, WeasyPrint или другого backend.

Не все направления преобразования равноценны. DOCX содержит стили, секции, колонтитулы, плавающие объекты, исправления и множество специфических свойств, которые не имеют прямого аналога в простом AST. При чтении Pandoc старается сохранить структуру, но не обещает точную копию макета. Аналогично, HTML может содержать сценарии, сложный CSS и интерактивные компоненты, которые не превращаются в редактируемые элементы Word. Практическое правило: чем семантичнее исходный документ и чем меньше в нём ручного позиционирования, тем предсказуемее результат.

Как Pandoc определяет формат

Если указан выходной файл, Pandoc обычно выбирает writer по его расширению: .docx ведёт к DOCX, .epub — к EPUB, .html — к HTML, .pdf — к цепочке генерации PDF. Однако расширение не описывает диалект Markdown и не всегда однозначно определяет XML-формат. Поэтому в повторяемой сборке лучше явно фиксировать from и to, особенно если документ проходит через несколько систем.

Имя формата можно дополнять расширениями через знаки плюс и минус. Запись markdown+smart включает типографские преобразования, а markdown-raw_html запрещает сырые HTML-блоки в этом reader. Набор доступных расширений различается для reader и writer. Если в команде указано неподдерживаемое расширение, Pandoc завершится с ошибкой, а не молча проигнорирует настройку; это полезно для выявления опечаток в сценариях.

Для GitHub-подобного ввода применяют gfm, для строгой совместимости с CommonMark — commonmark или commonmark_x, для собственного расширенного диалекта — markdown. Смена reader влияет не только на таблицы и сноски, но и на обработку переносов строк, необязательных атрибутов, зачёркивания, списков задач и сырой разметки. Нельзя считать все файлы с расширением .md одинаковыми: профиль синтаксиса должен быть частью проекта.

Расширенный Markdown Pandoc

В собственном диалекте Markdown поддерживаются YAML-метаданные, сноски, таблицы, списки определений, зачёркивание, верхние и нижние индексы, атрибуты заголовков, ограждённые блоки кода, математические формулы и цитирования. Благодаря этому один исходник может служить основой для HTML, DOCX, EPUB и PDF. Однако портируемость зависит от того, какие элементы понимает целевой writer. Например, математический блок может стать объектом формулы Word, MathML, LaTeX-кодом или изображением в зависимости от направления.

Заголовки лучше писать через решётки и не пропускать уровни без причины. Pandoc создаёт идентификаторы автоматически, используя текст заголовка и правила выбранного расширения. Эти идентификаторы нужны оглавлению и внутренним ссылкам. При коллизии добавляется суффикс; поэтому два раздела с одинаковым названием могут получить разные адреса. Если стабильность ссылок важна, задавайте идентификатор явно: ## Установка {#install}.

Атрибуты применимы к блокам, фрагментам, изображениям и другим элементам. Класс может управлять CSS в HTML, поведением фильтра или оформлением в шаблоне. Не стоит ожидать, что произвольный класс автоматически превратится в стиль Word: для DOCX сопоставление ограничено логикой writer и именами поддерживаемых пользовательских стилей. Когда нужен точный контроль, проверяют структуру полученного DOCX и корректируют reference.docx либо Lua-фильтр.

Преобразование Markdown в HTML

Без ключа --standalone Pandoc создаёт HTML-фрагмент: заголовки, абзацы, списки и другие элементы без html, head и полного каркаса страницы. Такой результат удобно вставлять в шаблон сайта или CMS. Команда pandoc article.md -t html5 -o fragment.html сохраняет именно содержимое. Метаданные документа при этом не превращаются в полноценный заголовок страницы, если template не используется.

Ключ -s или --standalone подключает шаблон и создаёт самодостаточный HTML-документ. Опции --toc и --number-sections добавляют оглавление и нумерацию. CSS подключают через --css, а ресурсы можно встроить в файл с помощью --embed-resources, если writer и тип ресурса допускают это. Встраивание удобно для передачи одного файла, но увеличивает размер и усложняет обновление общих стилей.

Параметр --section-divs оборачивает разделы в контейнеры, что помогает CSS и скриптам находить целые секции. --id-prefix добавляет префикс к идентификаторам, предотвращая конфликт при объединении нескольких фрагментов на одной странице. Для подсветки кода выбирают встроенный стиль или отключают её. Если исходник содержит сырой HTML, Pandoc может пропустить его в результат; при обработке непроверенного текста такой HTML требуется очищать отдельным санитайзером.

DOCX для редактирования в офисных программах

Команда pandoc report.md -o report.docx формирует пакет Office Open XML. Заголовки становятся абзацами соответствующих стилей, списки получают нумерацию, таблицы — структуру Word, сноски — отдельные объекты, а математические выражения по возможности записываются как редактируемые формулы. Результат следует проверять в целевой офисной программе, поскольку Word, LibreOffice и другие редакторы могут по-разному отображать поля, шрифты и переносы.

Pandoc не переносит дизайн Markdown: у исходника нет шрифтов, полей и колонтитулов. Эти свойства берутся из reference.docx. Чтобы получить образец, выполняют pandoc -o custom-reference.docx --print-default-data-file reference.docx, затем открывают файл в Word или совместимом редакторе, меняют стили, размер страницы, поля, свойства документа, верхний и нижний колонтитулы и сохраняют. При сборке добавляют --reference-doc=custom-reference.docx.

Содержимое reference.docx игнорируется; важны стили и свойства. Поэтому нельзя положить туда готовую титульную страницу и ожидать, что она автоматически появится. Для вставки обязательных блоков используют шаблонные возможности, метаданные, include-файлы, отдельный исходник или последующую обработку DOCX. В проектах с корпоративным оформлением reference.docx хранят рядом с исходниками и тестируют после обновления офисного пакета.

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

Стили Word и reference.docx

Перед правкой образца полезно создать тестовый Markdown, в котором присутствуют все используемые элементы: заголовки нескольких уровней, обычный абзац, цитата, маркированный и нумерованный списки, таблица, подпись изображения, код, сноска и формула. После первой конвертации видно, какие стили Pandoc назначает каждому элементу. Менять нужно именно эти стили, а не форматировать один тестовый абзац вручную, иначе новые абзацы в следующем документе останутся без оформления.

Поля страницы, ориентация, колонтитулы и свойства раздела также берутся из образца. Но разрывы разделов и разные ориентации внутри одного документа требуют дополнительной логики: стандартный writer не предоставляет универсальную Markdown-команду для любого свойства Word. Такие задачи решают raw OpenXML, фильтрами или постобработкой, понимая, что решение становится привязано к DOCX.

Изображения вставляются в медиакаталог DOCX. Их физический размер определяется атрибутами ширины и высоты либо внутренним DPI; если данных нет, используется значение --dpi. Поэтому один и тот же PNG может оказаться слишком крупным после конвертации. Надёжнее задавать размер в исходнике и сохранять изображения с корректной информацией о разрешении.

Для таблиц важны ширины колонок и тип таблицы в AST. Простая pipe table хорошо подходит для коротких данных, но не выражает все свойства Word. Объединённые ячейки, сложные заголовки и многоабзацное содержимое лучше сначала проверять в расширенных таблицах Pandoc или генерировать фильтром. Даже при корректной структуре автоматический подбор ширины в Word может потребовать ручной настройки стилей таблицы.

Как Pandoc создаёт PDF

При выходном расширении .pdf Pandoc не рисует страницы собственным движком. Он преобразует документ в промежуточный формат и запускает выбранную программу верстки. По умолчанию для обычного Markdown часто используется LaTeX-цепочка, поэтому без установленного PDF-движка команда завершается сообщением о том, что исполняемый файл не найден. Установка одного Pandoc не гарантирует готовность генерации PDF.

Параметр --pdf-engine позволяет выбрать подходящий backend. В документации перечислены pdflatex, lualatex, xelatex, latexmk, tectonic, wkhtmltopdf, weasyprint, pagedjs-cli, prince, context, groff, pdfroff и typst. Доступность конкретного имени проверяется в установленной версии. Если исполняемый файл не находится через PATH, передают полный путь.

Выбор движка определяет возможности и синтаксис настройки. XeLaTeX и LuaLaTeX удобны для системных шрифтов и Unicode; pdfLaTeX требует более осторожной работы с кодировками и шрифтами. Typst предлагает иной шаблон и набор переменных. HTML-движки используют CSS и правила печати, но могут отличаться в поддержке сносок, переносов и математической верстки. Нельзя переносить опции одного backend на другой без проверки.

Чтобы понять место ошибки, запустите конвертацию с --verbose и сохраните промежуточный файл отдельно: например, сначала создайте report.tex или report.html. Если промежуточный документ правильный, исследуют настройки движка. Если структура неверна уже там, исправляют исходник, reader, шаблон или фильтр.

Выбор PDF-движка

Для отчётов с формулами, перекрёстными ссылками и академическим оформлением чаще выбирают LaTeX. XeLaTeX позволяет указать основной шрифт через переменные шаблона и нормально работает с кириллицей при наличии подходящего шрифта. LuaLaTeX решает похожие задачи и полезен в проектах, где уже применяются LuaLaTeX-пакеты. pdfLaTeX может дать стабильный результат в старой инфраструктуре, но Unicode и современные шрифты требуют дополнительных настроек.

Typst удобен, когда команда проекта использует его шаблоны и хочет более быстрый цикл верстки. Но LaTeX-шаблон и переменные не совместимы с Typst-шаблоном. При переходе нужно отдельно перенести поля, шрифты, титульный блок, стили заголовков и обработку таблиц. В новой версии Typst также могут изменяться элементы шаблона, поэтому движок и Pandoc фиксируют в окружении сборки.

WeasyPrint, wkhtmltopdf, Paged.js и Prince строят PDF из HTML. Их выбирают, когда дизайн уже описан CSS и тот же контент публикуется в браузере. Различия проявляются в поддержке CSS Paged Media, колонтитулов, нумерации страниц и переносов. В команде Pandoc задают HTML как промежуточный writer и передают движку нужные аргументы через --pdf-engine-opt.

Groff, pdfroff и ConTeXt подходят для специализированных рабочих процессов. Важно не выбирать движок только по наличию в системе. Сначала составляют тестовый документ с кириллицей, таблицами, изображениями, длинными ссылками, формулами и сносками, затем сравнивают результат и время сборки. После выбора фиксируют версии и параметры, иначе обновление движка может изменить переносы строк и число страниц.

Поля, шрифты и разрывы страниц в PDF

В LaTeX-цепочке поля часто задают переменной geometry: -V geometry:margin=2cm. Для разных сторон передают составное значение. Шрифты при XeLaTeX или LuaLaTeX задаются переменными mainfont, sansfont и monofont, но выбранные гарнитуры должны быть установлены в окружении сборки и содержать нужные глифы. Если кириллица заменяется пустыми прямоугольниками, проблема обычно не в Markdown, а в шрифте или движке.

Разрывы страниц не имеют единого переносимого синтаксиса для всех writer. Raw LaTeX-команда сработает в LaTeX/PDF и исчезнет либо превратится в текст в других форматах. Raw HTML с CSS подходит HTML-цепочке, но не DOCX. Для многоканальной публикации лучше помечать место нейтральным классом и преобразовывать его Lua-фильтром в элемент, соответствующий целевому формату.

Большие таблицы в LaTeX часто превращаются в longtable и могут переходить на следующую страницу. Это полезно для отчётов, но не подходит некоторым двухколоночным макетам. Атрибуты таблицы и шаблон позволяют выбирать иное поведение, однако необходимо проверять заголовок, повторение строк и ширину колонок. Автоматическое уменьшение шрифта не является универсальной функцией Pandoc: его реализует шаблон или пакет верстки.

При проблемах с изображениями смотрят путь к файлу, формат, DPI и поддержку движка. SVG может потребовать конвертер или быть обработан по-разному. Если backend не понимает формат, Pandoc иногда пытается преобразовать его через доступные средства, но полагаться на неявную конвертацию в воспроизводимой сборке рискованно. Лучше заранее нормализовать графику в поддерживаемый формат.

Таблицы: от Markdown до целевого документа

Pandoc различает несколько видов таблиц Markdown: простые, многострочные, grid и pipe tables. Pipe table быстрее писать, но сложное содержимое, объединения и многоабзацные ячейки требуют более выразительного синтаксиса или генерации AST. В новых форматах таблица может иметь подпись, идентификатор, классы и атрибуты. Эти данные writer использует настолько, насколько позволяет целевой формат.

Выравнивание колонок задаётся разделителем в pipe table или спецификацией колонок. Относительные ширины помогают HTML, DOCX и LaTeX writer, но итоговый просмотрщик может перераспределить место. Длинное непрерывное слово или URL заставляет колонку расширяться и ломает ожидаемую верстку; проблему решают переносимым сокращением текста, мягкими переносами или стилями целевого формата.

Объединённые ячейки поддерживаются не во всех входных синтаксисах и не всеми writer одинаково. Если таблица пришла из DOCX, часть структуры может сохраниться, но сложные стили границ и заливок не переносятся как универсальные свойства. Для отчётности с жёстким шаблоном иногда рациональнее генерировать таблицу непосредственно в DOCX или LaTeX через фильтр.

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

Изображения и поиск ресурсов

В Markdown изображение обычно задаётся относительным путём. Pandoc ищет ресурс относительно рабочей директории и путей из --resource-path. Если сборка запускается из другой папки, картинка может пропасть, хотя исходник не менялся. Надёжный проект задаёт корень ресурсов явно и не зависит от текущей директории терминала.

Опция --extract-media=media извлекает изображения из контейнерных входных форматов, например DOCX или EPUB, и переписывает ссылки в создаваемом документе. Это полезно при переносе материала в Markdown: текст и структура оказываются в одном файле, медиа — в отдельном каталоге. После извлечения нужно проверить имена, дубликаты и фактическое качество картинок, потому что исходный офисный документ мог содержать миниатюры или несколько вариантов одного объекта.

Параметр --fetch-resources и чтение удалённых ресурсов упрощают единичную конвертацию, но ухудшают воспроизводимость и требуют сетевого доступа. Для стабильной публикации изображения сохраняют в репозитории, проверяют лицензии и фиксируют хеши. Если сеть недоступна или адрес изменился, локальная сборка продолжит работать.

Атрибуты width и height могут задаваться в пикселях, процентах или физических единицах, но поддержка зависит от writer. Процентная ширина естественна для HTML, а DOCX и LaTeX преобразуют её в собственные размеры. Не задавайте одновременно противоречивые ширину и высоту: сохранение пропорций становится зависимым от writer.

Формулы и математическая разметка

В исходном Markdown формулы обычно пишутся в синтаксисе LaTeX: одиночные доллары для встроенного выражения и двойные для отдельного блока. Pandoc разбирает математическое содержимое и передаёт его writer. В DOCX формула может стать нативным объектом Office Math, в HTML — MathML, MathJax или другим выбранным представлением, в LaTeX — остаться математическим кодом.

Для HTML способ задают параметрами математического рендеринга. MathJax удобен для сложных выражений, но добавляет зависимость от сценария в браузере. MathML не требует JavaScript в поддерживающем браузере, однако отображение может отличаться. WebTeX создаёт изображения и требует доступного сервиса или локальной схемы. Выбор должен учитывать офлайн-просмотр, доступность и требования сайта.

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

Если PDF собирается через XeLaTeX, ошибка формулы обычно появляется в журнале движка. Сохраните промежуточный .tex, найдите строку и проверьте баланс скобок, доступность пакета и корректность команды. Если DOCX открывается с повреждённой формулой, сравните её с упрощённым вариантом и проверьте, поддерживает ли конвертер конкретную конструкцию.

Цитирования и библиография

Встроенная обработка цитат включается ключом --citeproc. В тексте используются библиографические идентификаторы, например [@smith2024], а библиографические данные читаются из BibTeX, BibLaTeX, CSL JSON, CSL YAML и других поддерживаемых представлений. Стиль оформления задаётся CSL-файлом. Pandoc формирует ссылки в тексте и список литературы в выходном формате.

Ключ цитаты должен точно совпадать с записью в базе. Если запись не найдена, в результате остаётся заметный маркер, а в stderr появляется предупреждение. В CI такие предупреждения следует считать ошибкой, иначе документ уйдёт на публикацию с необработанными ссылками. Проверяйте также обязательные поля: отсутствие автора или даты может быть допустимо, но выбранный CSL-стиль оформит запись иначе.

Локаль цитирования влияет на подписи, сокращения и порядок элементов. Язык документа задаётся метаданными, а отдельные записи могут иметь собственные языковые поля. Для русскоязычного текста полезно проверить и др., формат дат, тире, кавычки и сортировку кириллических авторов. Разные CSL-стили предполагают разные правила и не всегда одинаково работают с смешанной латиницей и кириллицей.

Список литературы можно разместить в нужном месте через специальный контейнер с идентификатором refs. Без него bibliography обычно добавляется в конце. Для DOCX стили библиографии настраивают reference.docx, для HTML — CSS, для LaTeX — шаблон и пакеты. Citeproc отвечает за содержание и последовательность, но не заменяет визуальные стили целевого формата.

Подсветка программного кода

Ограждённый блок кода получает язык через класс, например ```python. Pandoc использует библиотеку синтаксической подсветки и умеет перечислять доступные языки и стили. Параметр --syntax-highlighting выбирает схему, а --no-highlight отключает разбор. Если имя языка не распознано, код обычно остаётся моноширинным без ожидаемой раскраски.

В HTML подсветка может быть записана встроенными стилями и классами. Для самостоятельной страницы template добавляет необходимые правила. В DOCX цвета и стили представляются средствами Word, но точное соответствие HTML-схеме не гарантируется. В LaTeX writer генерирует определения, которые должны поддерживаться шаблоном и пакетами.

Длинные строки кода — частая причина выхода за поля PDF. Pandoc не может безопасно перенести любую строку, потому что пробелы и символы могут быть значимы. Решение выбирают на уровне шаблона: уменьшение размера шрифта, включение переноса, использование более широкого листинга или предварительное форматирование исходника. Для DOCX можно настроить стиль Source Code и разрешить перенос в редакторе.

Пользовательские синтаксисы подключаются через файл определения. Его путь нужно включить в проект и передавать опцией, а не рассчитывать на личный каталог одного сотрудника. Воспроизводимость проверяют командой, которая перечисляет доступные языки в чистом окружении сборки.

Создание EPUB

Команда pandoc book.md -o book.epub создаёт контейнер электронной книги с XHTML-разделами, оглавлением, метаданными и ресурсами. Заголовки исходника определяют структуру навигации. Для длинной книги удобно объединить несколько файлов в правильном порядке или использовать файл defaults со списком input-files.

Обложку задают отдельной опцией, таблицу стилей — CSS, метаданные — YAML-блоком или отдельным файлом. В EPUB можно встраивать шрифты, но это увеличивает размер и требует права на распространение. Не каждый ридер одинаково поддерживает CSS, поэтому сложную сетку, фиксированное позиционирование и сценарии следует исключать.

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

EPUB является ZIP-пакетом, поэтому техническую проверку можно выполнить программой проверки ZIP и валидатором EPUB. Наличие файла ещё не означает соответствие стандарту. Ошибки чаще связаны с отсутствующими изображениями, неверными идентификаторами, метаданными и CSS. Pandoc формирует корректную основу, но ответственность за контент и ресурсы остаётся у автора.

Презентации PowerPoint и слайды

Pandoc может создавать PPTX из Markdown. Границы слайдов определяются уровнями заголовков и горизонтальными разделителями в зависимости от структуры. Текстовые блоки, списки, изображения и заметки преобразуются в элементы презентации. Для предсказуемого результата исходник должен быть короче обычной статьи: Pandoc не умеет автоматически превратить переполненный слайд в удачную композицию.

Оформление задаётся reference.pptx. Образец содержит мастер, макеты, тему, шрифты и геометрию заполнителей. Лучше получить стандартный reference-файл из Pandoc, изменить его и использовать как основу. Если взять произвольную корпоративную презентацию, имена и типы макетов могут не совпасть с ожиданиями writer.

Картинки следует готовить под соотношение сторон презентации. Атрибуты размеров помогают, но заполнители и макет могут ограничить итог. Таблицы с большим числом строк почти наверняка выйдут за границы; их лучше разделить на несколько слайдов или заменить диаграммой, созданной заранее.

Для HTML-слайдов доступны writers reveal.js, Slidy, Slideous, S5 и DZSlides. Они используют другой набор параметров и могут требовать внешних ресурсов. Выбор между PPTX и HTML зависит от среды показа: PowerPoint удобен для ручной доработки, HTML — для веб-публикации и версионного контроля.

ODT, RTF и обмен с текстовыми редакторами

ODT подходит для обмена с LibreOffice и другими редакторами OpenDocument. Как и DOCX, он использует reference-документ для стилей и свойств. Содержание образца игнорируется, а оформление новых элементов берётся из его стилей. При сложных таблицах, формулах и колонтитулах результат необходимо проверять именно в редакторе, в котором документ будет дорабатываться.

RTF удобен как более простой формат совместимости, но его модель уступает современным офисным контейнерам. Часть структурных элементов и сложного оформления будет упрощена. RTF разумно использовать для коротких документов, когда получатель не может открыть DOCX или ODT, а не как основной мастер-формат для большой книги.

При конвертации из офисного документа в Markdown сначала извлекают медиа и оценивают структуру заголовков. Абзац, визуально похожий на заголовок, может быть обычным абзацем с крупным шрифтом; Pandoc не обязан распознавать дизайнерский замысел. Чем дисциплинированнее применялись стили в исходнике, тем качественнее результат.

Изменения, комментарии, поля, макросы и сложные встроенные объекты не следует считать переносимыми. Перед миграцией важного документа сохраните оригинал, сформируйте тестовый результат и составьте перечень потерь. Pandoc предназначен для преобразования содержания, а не для полного клонирования всех внутренних свойств офисного файла.

Шаблоны и самостоятельные документы

Шаблон используется, когда включён --standalone. Он добавляет заголовок, служебные элементы и оболочку, необходимую выбранному формату. Посмотреть встроенный шаблон можно командой pandoc -D html, pandoc -D latex или с другим именем writer. Пользовательский файл передают через --template либо помещают в каталог templates пользовательского data-dir.

Синтаксис шаблонов поддерживает переменные, условия, циклы и разделители. Значения приходят из метаданных и параметров -V. Например, template может выводить автора только при наличии поля, повторять список CSS-файлов или менять блок заголовка для определённого класса документа. Сложную бизнес-логику лучше не переносить в шаблон: её труднее тестировать, чем фильтр или предварительную обработку данных.

Для DOCX, ODT и PPTX основной визуальный контроль обеспечивают reference-документы, а не обычные текстовые шаблоны. Для PDF выбор зависит от промежуточного writer: LaTeX использует latex template, HTML-движок — HTML template, Typst — Typst template. Ошибка выбора приводит к ситуации, когда пользователь меняет файл, который вообще не участвует в сборке.

Шаблон храните вместе с проектом и вызывайте относительным путём. Если положить его только в пользовательский каталог одного компьютера, коллеги и CI получат другой результат. Для обновления встроенного шаблона сравнивают старую пользовательскую копию с новой системной: в ней могут появиться переменные и блоки, необходимые writer.

Файлы defaults вместо длинной команды

Опция --defaults читает YAML или JSON с параметрами конвертации. В файл можно перенести input-files, from, to, output-file, standalone, table-of-contents, filters, metadata, variables, resource-path, reference-doc и параметры конкретного writer. Команда становится короткой: pandoc --defaults publish.

Defaults сначала ищется в рабочей директории, затем в подкаталоге defaults пользовательского data-dir. Если файл без расширения не найден, Pandoc может попробовать вариант .yaml. Это позволяет хранить профили web.yaml, word.yaml и pdf.yaml и вызывать их одинаково на разных платформах.

Пути внутри некоторых полей поддерживают подстановки переменных окружения, USERDATA и каталога самого defaults-файла. Последняя возможность особенно полезна: профиль может ссылаться на лежащие рядом шаблон, CSS, CSL и обложку, независимо от рабочей папки. При этом переменные интерполируются только в полях, где ожидается путь.

Несколько defaults-файлов объединяются, а параметры командной строки дополняют или переопределяют настройки. Для повторяемости документируйте порядок подключения. Поля, допускающие повторение, могут объединяться вместо простой замены; поэтому после добавления нового профиля проверяйте итоговую команду на дублирующиеся CSS, metadata-file или filter.

Метаданные документа

Метаданные помещают в YAML-блок в начале Markdown, передают через --metadata или загружают отдельным файлом. Типичные поля — title, author, date, lang, subtitle, keywords и abstract. Writer и template используют только известные имена или явно выведенные пользовательские переменные; наличие поля само по себе не гарантирует, что оно появится в результате.

Массив авторов лучше записывать YAML-списком, а не строкой с запятыми. Вложенные структуры полезны для шаблонов, но не каждый writer умеет преобразовать их в свойства документа. Для DOCX часть метаданных попадает в пакет, часть отображается на титульном блоке, если template это предусматривает.

Параметр --metadata-file удобен, когда одинаковое содержание выпускается для разных клиентов или языков. Один Markdown остаётся неизменным, а отдельные YAML-файлы задают название, дату, статус и оформление. При конфликте важен порядок применения; итог нужно проверять, а не предполагать, что значение из конкретного файла всегда победит.

Дата в метаданных является текстом с точки зрения многих шаблонов. Если требуется единый формат, нормализуйте её до конвертации или примените фильтр. Автоматическая текущая дата ухудшает воспроизводимость: повторная сборка того же коммита создаёт другой документ. Для официальных выпусков дату передают явно.

Lua-фильтры и преобразование структуры

Фильтр получает элементы внутреннего документа и возвращает изменённые элементы. Lua встроен в типичную сборку Pandoc, поэтому простой фильтр не требует отдельного интерпретатора. Функция Header может изменить заголовки, Image — нормализовать размеры, CodeBlock — обработать листинги, а Pandoc — работать со всем документом.

Опция --lua-filter=filter.lua подключает файл. Несколько фильтров выполняются в указанном порядке, поэтому перестановка может изменить результат. Например, первый фильтр создаёт div с классом, а второй преобразует этот класс в raw-элемент целевого формата. Если второй запустить раньше, он ничего не найдёт.

Фильтры решают задачи, которых нет в базовом Markdown: условные блоки для разных выходов, автоматические подписи, преобразование специальных shortcodes, вставка разрывов страниц, обработка диаграмм, проверка ссылок и генерация производных элементов. Но фильтр также способен читать и записывать файлы, запускать процессы и обращаться к сети через доступные средства. Код неизвестного происхождения нужно рассматривать как обычную программу.

Для устойчивости фильтр проверяет типы и отсутствующие поля, не привязывается к случайному тексту и имеет тестовые примеры. При обновлении Pandoc сверяют изменения API и запускают набор контрольных документов. Если фильтр меняет структуру для нескольких writer, тесты должны охватывать каждый целевой формат.

JSON AST и native-представление

Промежуточное дерево можно вывести writer-ом json или native. JSON подходит для программ на любом языке: процесс читает структуру из stdin, изменяет её и возвращает JSON. Native удобен человеку для диагностики, потому что компактно показывает Header, Para, Str, Space, Table, Image и другие конструкторы.

AST помогает отличить ошибку reader от ошибки writer. Если текст, который должен быть заголовком, представлен как Para, настройка DOCX-стиля не поможет. Если дерево содержит Header, но в результатe нет правильного оформления, исследуют writer и reference-документ. То же относится к таблицам, сноскам и атрибутам.

Формат JSON содержит версию API. Внешний фильтр должен использовать совместимую библиотеку или хотя бы проверять поле версии. Жёстко прописанный обход массивов, рассчитанный на старую структуру таблицы, может сломаться после обновления. Lua-фильтры меньше зависят от сериализации, потому что работают через встроенные типы.

Не стоит редактировать большой JSON вручную как основное представление. Он многословен и чувствителен к деталям внутренней модели. Используйте его для обмена между процессами, тестовых снимков и анализа, а исходное содержание храните в читаемом формате.

Потоки stdin и stdout

Если входной файл не указан, Pandoc читает стандартный ввод. Это позволяет передать текст из другой команды: генератор данных создаёт Markdown, Pandoc преобразует его в HTML, а следующий процесс выполняет упаковку. Для текстовых writer результат по умолчанию идёт в stdout; двоичные форматы обычно требуют -o, хотя принудительный вывод в поток возможен.

При работе с каналами важно разделять stdout и stderr. Документ идёт в stdout, предупреждения — в stderr. Если объединить потоки, ошибка попадёт внутрь HTML или JSON и повредит результат. В shell-сценарии перенаправляйте их отдельно и проверяйте код завершения каждого процесса, особенно в длинной цепочке.

Кодировка входа должна быть UTF-8. Файлы из старых систем сначала перекодируют. На Windows в старом cmd также может потребоваться переключить кодовую страницу для корректного отображения терминального вывода, хотя содержимое файлов остаётся отдельным вопросом. Не пытайтесь исправить неправильную кодировку выбором PDF-шрифта: повреждение произошло до этапа верстки.

Имена файлов с пробелами заключают в кавычки. В кроссплатформенных сценариях используйте средства языка программирования для формирования списка аргументов, а не склеивайте командную строку вручную. Это предотвращает ошибки с кавычками и снижает риск внедрения команд через имя файла.

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

Pandoc обрабатывает один документ за запуск, но shell, PowerShell, Make, Python и системы сборки легко перебирают каталог. В пакетном процессе для каждого файла формируют уникальное имя результата, сохраняют журнал и останавливаются при ошибке. Параллельный запуск ускоряет независимые конвертации, но PDF-движки и шрифтовые кэши могут конфликтовать или потреблять много памяти.

Make и похожие инструменты полезны тем, что пересобирают только устаревшие результаты. Зависимостями должны быть не только Markdown-файлы, но и шаблон, reference.docx, CSS, CSL, библиография, фильтры и изображения. Если забыть ресурс, изменение оформления не запустит новую сборку.

В CI устанавливают фиксированные версии Pandoc и PDF-движка, копируют шрифты с разрешённой лицензией и выполняют smoke-тест. Для двоичных результатов проверяют, что файл открывается и имеет ожидаемый тип; для HTML можно дополнительно валидировать структуру. Сравнение PDF побайтно часто бесполезно из-за метаданных и временных значений, поэтому применяют визуальный diff или извлечение текста.

Официальные Docker-образы разделяют базовый вариант и вариант с минимальной LaTeX-средой. Контейнер помогает воспроизводимости, но нужно правильно смонтировать рабочий каталог и назначить пользователя, иначе файлы результата будут принадлежать root. Сетевые ресурсы и системные шрифты контейнер не получает автоматически.

Пользовательский каталог данных

Путь к data-dir отображается в pandoc --version. В нём можно хранить templates, defaults, reference.docx, reference.odt, epub.css, CSL и другие данные. Файлы из пользовательского каталога переопределяют встроенные значения, что удобно для личной настройки, но может сделать результат зависимым от конкретного компьютера.

Для командного проекта лучше держать критические ресурсы в репозитории и указывать их явно. Пользовательский data-dir оставляют для общих инструментов, которые не влияют на официальный выпуск. Если локально документ выглядит иначе, чем в CI, первым делом сравните data-dir и наличие файлов с именами по умолчанию.

Параметр --data-dir задаёт другой каталог. Это позволяет создать изолированное окружение проекта и исключить личные настройки. Полезный тест — запустить сборку с пустым временным data-dir: если она ломается, проект не содержит какой-то неявной зависимости.

Старые установки могли использовать другой путь для совместимости. Не переносите каталог вслепую между версиями: шаблоны и reference-файлы могли измениться. Сначала создайте результат с новыми встроенными данными, затем переносите только нужные изменения и сравнивайте.

Переносы строк, ширина и окончания строк

Опция --wrap управляет переносами в текстовом исходнике результата, а не визуальным переносом в браузере или Word. Значение auto переносит строки около заданной ширины, none оставляет длинные строки, preserve старается сохранить несемантические переносы входа. Для HTML и Markdown в системе контроля версий часто выбирают none или согласованный columns, чтобы diff был предсказуемым.

--columns влияет на форматирование текстовых writer и некоторые расчёты. Он не устанавливает ширину страницы PDF. Для PDF ширину определяют поля и шаблон движка. Смешивание этих понятий приводит к попыткам лечить переполнение таблицы параметром, который меняет только исходный текст.

Опция --eol выбирает LF, CRLF или системное окончание строк. Она полезна при генерации файлов для старых инструментов и репозиториев с жёсткой политикой. Для двоичных DOCX, EPUB и PDF значение не относится к внутреннему представлению всех файлов пакета.

В Markdown одиночный перенос строки обычно не означает новый абзац. Поведение зависит от reader и расширений hard_line_breaks или east_asian_line_breaks. Текст, скопированный из редактора с переносом каждой визуальной строки, может превратиться в неожиданные пробелы или разрывы. Перед конвертацией нормализуйте такие файлы.

Безопасная обработка непроверенных документов

Опция --sandbox ограничивает операции ввода-вывода readers и writers файлами, явно указанными в команде. Она снижает риск чтения посторонних файлов через include-механизмы. Однако sandbox не ограничивает фильтры и процесс создания PDF, поэтому небезопасный Lua-фильтр или PDF-движок сохраняет возможности обычной программы.

Raw HTML из пользовательского Markdown может попасть в выходной HTML. Даже при отключённом raw_html опасные значения могут находиться в ссылках и атрибутах. Публикуемый результат пропускают через санитайзер с политикой сайта. Pandoc преобразует разметку, но не является системой очистки HTML.

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

Парсеры могут тратить чрезмерное время на патологический ввод. Серверный процесс должен иметь timeout и лимит памяти. Для непроверенного Markdown CommonMark-парсеры менее восприимчивы к некоторым тяжёлым случаям, но это не отменяет общих ограничений ресурсов.

Типичные предупреждения и ошибки

Сообщение Unknown input format или Unknown output format означает неверное имя reader или writer. Сверьте его с --list-input-formats и --list-output-formats. Опечатка в расширении после плюса вызывает отдельную ошибку; проверяйте --list-extensions для выбранного формата.

Ошибка Could not find data file указывает на отсутствующий template, reference-документ или другой ресурс. Проверьте относительный путь, рабочую директорию и data-dir. В sandbox-режиме файл должен быть доступен по правилам ограничения. Не копируйте случайный файл под ожидаемым именем: writer может требовать определённую структуру.

Сообщение о ненайденном xelatex, pdflatex, typst или другом engine означает, что программа не установлена либо отсутствует в PATH. Выполните команду движка отдельно, затем укажите полный путь или исправьте переменную окружения. Установка пакета Python с похожим названием не обязательно добавляет требуемый исполняемый файл.

Предупреждение о недоступном изображении содержит путь, который Pandoc пытался открыть. Сравните регистр символов: Windows часто скрывает ошибку, а Linux различает Image.png и image.png. Проверьте resource-path и запуск из CI. Для удалённого ресурса сохраните локальную копию.

Необработанная цитата выглядит как ключ в квадратных скобках. Убедитесь, что включён citeproc, подключена библиография и ключ совпадает. Ошибка в CSL-файле может прервать обработку; временно уберите пользовательский стиль, чтобы отделить проблему данных от проблемы оформления.

Практическая диагностика по этапам

Первый тест — минимизировать исходник. Скопируйте проблемный фрагмент в отдельный файл и удаляйте элементы, пока ошибка не исчезнет. Такой пример легче проверить с другим reader, writer и движком. Большой документ часто скрывает настоящую причину десятками вторичных сообщений.

Второй тест — вывести native AST. Если проблемного элемента нет или он имеет неверный тип, настройте входной синтаксис. Для Markdown проверьте пустые строки, отступы и включённые расширения. Для DOCX убедитесь, что автор применил семантический стиль, а не только визуальное форматирование.

Третий тест — создать промежуточный формат. Для PDF сохраните LaTeX, HTML или Typst и запустите engine вручную. Для DOCX распакуйте контейнер в копию каталога и посмотрите styles.xml, document.xml и media. Для EPUB проверьте manifest и ссылки внутри XHTML.

Четвёртый тест — заменить пользовательские ресурсы встроенными. Уберите filter, template, reference-doc, CSS и defaults по одному. Если ошибка исчезла, возвращайте компоненты постепенно. Это быстрее, чем одновременно менять исходник, шаблон и версию движка.

Пятый тест — чистое окружение. Запустите команду в контейнере или новой учётной записи с явными путями. Разница указывает на скрытый data-dir, шрифты, переменные окружения или иную программу с тем же именем в PATH.

Ограничения преобразования

Внутренняя модель Pandoc намеренно описывает общие структурные элементы. Она не может выразить каждое свойство Word, CSS, InDesign, LaTeX и презентационных форматов одновременно. Поэтому преобразование между двумя богатыми форматами всегда является отображением через более общий набор элементов, а не прямым импортом всех внутренних данных.

Готовый PDF не является входным форматом для восстановления документа. PDF хранит команды размещения текста и графики, а не исходную структуру заголовков, абзацев и таблиц. Для извлечения текста, OCR или визуального редактирования нужны другие инструменты. Pandoc применяют до появления PDF, когда исходник ещё структурирован.

Сложный макет с плавающими блоками, несколькими колонками, формами, мультимедиа и интерактивностью потребует целевого шаблона или специализированного writer. Универсальная команда не угадает дизайнерское решение. Лучше определить мастер-формат и допустимый уровень различий между каналами.

Преобразование веб-страницы в Markdown сохраняет содержимое, доступное reader, но не выполняет JavaScript как полноценный браузер и не воспроизводит приложение. Динамические таблицы и данные могут отсутствовать. Сначала получите статический HTML или экспорт из системы.

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

Импорт DOCX и ODT в Markdown

При переносе офисного документа в Markdown команда указывает исходный контейнер и текстовый writer, например pandoc manual.docx -t markdown -o manual.md. Качество зависит от применения стилей в оригинале. Абзацы со стилями Heading становятся заголовками, настоящие списки — списками, а сноски — сносками. Если автор имитировал структуру размером шрифта, табуляцией и ручными номерами, Pandoc видит набор обычных абзацев и не обязан угадывать их роль.

Опцию --extract-media=media следует включать сразу, иначе изображения могут быть записаны как внутренние ссылки, неудобные для дальнейшей работы. После извлечения проверьте каталог: офисный пакет нередко хранит одинаковую графику под разными именами, уменьшенные копии и служебные объекты. Ссылки в Markdown будут указывать на созданные файлы, поэтому переименование нужно выполнять вместе с автоматическим обновлением путей.

Выбор выходного диалекта Markdown влияет на сохранение элементов. Собственный markdown writer способен записать больше конструкций Pandoc, чем строгий commonmark, но полученный файл может не полностью пониматься сторонним редактором. Для миграции в конкретную CMS сначала определите допустимый синтаксис, затем отключите неподдерживаемые расширения и проверьте таблицы, атрибуты, сноски и raw-блоки.

Стилизация теряется намеренно: цвет шрифта, точные отступы и большинство свойств страницы не являются универсальной семантикой Markdown. Если эти сведения нужны для будущего оформления, сохраните оригинальный reference-документ или перенесите значимые различия в классы через фильтр. Не пытайтесь превращать каждый визуальный нюанс в raw OpenXML: такой Markdown будет трудно читать и почти невозможно выводить в другие форматы.

Внутренние ссылки, идентификаторы и перекрёстные ссылки

Внутренняя ссылка Markdown указывает на идентификатор заголовка или другого элемента. Автоматические идентификаторы зависят от текста и выбранного набора расширений, поэтому переименование раздела может сломать ранее опубликованный адрес. Для документов, на которые ссылаются извне, задавайте стабильные идентификаторы вручную и не меняйте их при редактуре заголовка.

Опция оглавления использует те же идентификаторы. Если reader по умолчанию не создаёт их, Pandoc может включить соответствующее расширение при запросе TOC. Глубина задаётся отдельно: это ограничивает пункты в оглавлении, но не меняет уровни самих заголовков. В DOCX автоматическое оглавление может потребовать обновления полей после открытия в Word; в HTML ссылки работают сразу.

Нумерация разделов через --number-sections генерируется writer и не должна дублироваться числами, вручную вписанными в текст заголовка. Иначе получится 2 2 Установка, а внутренние ссылки и сортировка станут менее устойчивыми. Если отдельный раздел не нужно нумеровать, применяют поддерживаемый класс unnumbered, а не вставляют пробелы или скрытые символы.

Полноценные перекрёстные ссылки на рисунки, таблицы и формулы не сводятся к одному универсальному параметру для всех форматов. Их реализуют средствами выбранного writer, Lua-фильтрами или надстройками издательского процесса. Перед выбором решения проверьте, как ссылка выглядит в DOCX, HTML и PDF, как ведёт себя при перестановке объектов и сохраняется ли доступная подпись.

Журналы, предупреждения и коды завершения

При успешной операции Pandoc обычно не печатает подтверждение, поэтому сценарий должен опираться на код завершения и наличие ожидаемого файла. Ненулевой код означает, что документ нельзя считать выпущенным, даже если частичный файл успел появиться. Перед сборкой во временный путь и последующим атомарным перемещением можно защититься от публикации повреждённого результата.

Опция --verbose показывает больше сведений о чтении ресурсов, выборе форматов и вызове внешних инструментов. Для автоматического анализа доступен структурированный журнал, который можно записывать в файл и обрабатывать отдельно. Не смешивайте лог с stdout при генерации текстового документа: служебные строки окажутся внутри результата.

Предупреждения важны не меньше ошибок. Отсутствующее изображение, неразрешённая цитата или пропущенный символ могут не остановить конвертацию. В строгом процессе stderr сохраняют, ищут известные категории предупреждений и отклоняют сборку. Белый список допустимых сообщений должен быть узким и документированным, иначе новый дефект останется незамеченным.

Коды завершения различают классы ошибок: неверные параметры, проблемы чтения, записи, фильтра или PDF-движка. Shell-скрипту необязательно расшифровывать каждый номер, но полезно выводить понятный этап. Например, отдельно проверять генерацию промежуточного HTML и отдельно запуск WeasyPrint; тогда журнал сразу показывает, какая часть конвейера не сработала.

Чтение веб-страниц и удалённых ресурсов

Pandoc способен читать адрес как входной HTML и загружать связанные ресурсы в пределах поддерживаемого процесса. Это удобно для разовой миграции статической статьи, но результат зависит от сетевого ответа, кодировки и HTML, который сервер отдал именно в момент запуска. Для сохраняемой или повторяемой задачи сначала сохраняют страницу и ресурсы локально.

Динамический сайт может отдавать почти пустой каркас, который заполняется JavaScript после загрузки. Pandoc не является браузерным движком, поэтому интерактивная таблица, комментарии и данные приложения не появятся. Нужно получить статический экспорт, использовать API сайта или предварительно отрендерить страницу специализированным инструментом.

Удалённые изображения и таблицы стилей создают дополнительные точки отказа. Даже если первая сборка прошла, сервер может изменить адрес, потребовать авторизацию или вернуть файл другого типа. Для издательского проекта ресурсы копируют в управляемый каталог, проверяют их формат и указывают через resource-path.

При доступе к защищённому ресурсу можно передавать заголовки запроса, но секреты не следует хранить в defaults, который попадает в репозиторий. Используйте переменные окружения и безопасное хранилище CI, а журнал очищайте от токенов. Если документ поступает от внешнего пользователя, сетевой доступ процесса лучше отключить, чтобы вход не заставил сервер обращаться к произвольным адресам.

Сравнение Pandoc с аналогами

Программа	Лучше подходит для	Главное ограничение
Pandoc	Многоканальной конвертации структурированных документов, шаблонов, библиографий и автоматических сборок	Нет визуального редактора, а PDF зависит от отдельного движка
Quarto	Научных и технических публикаций с вычисляемым кодом, проектами, сайтами, книгами и презентациями	Добавляет собственный уровень проекта и не заменяет универсальный конвертер во всех сценариях
LibreOffice	Ручного редактирования офисных файлов и пакетного экспорта через headless-режим	Автоматизация сложнее контролируется на уровне семантической разметки
Calibre ebook-convert	Подготовки и перекодирования электронных книг между EPUB, MOBI, AZW и другими книжными форматами	Ориентирован на электронные книги, а не на общий издательский AST
Asciidoctor	Документации на AsciiDoc с расширениями, include-механизмами и специализированными backend	Основной входной язык — AsciiDoc, универсальность форматов ниже
MultiMarkdown	Документов на расширенном Markdown с таблицами, сносками и экспортом в ограниченный набор целей	Поддерживает меньше входных и выходных форматов
PDF Commander	Визуального редактирования, объединения, разбиения и оформления уже созданных PDF	Не является конвейером преобразования разметки в DOCX, EPUB и HTML

Pandoc выбирают, когда один структурированный документ нужно выпускать в нескольких форматах и процесс должен повторяться командой. Quarto удобнее для проектов с вычисляемыми блокнотами и сформированной системой сайта или книги. LibreOffice рациональнее, когда документ требуется вручную править в визуальном редакторе и сохранить офисное оформление. Calibre сильнее в специфической конвертации электронных книг, Asciidoctor — в больших проектах на AsciiDoc, MultiMarkdown — в более узком Markdown-процессе. PDF Commander нужен на последнем этапе, если требуется менять сам PDF, а не пересобирать его из исходника.

Когда Pandoc особенно полезен

Техническая документация выигрывает от хранения Markdown в системе контроля версий. Изменения видны построчно, шаблон и фильтры проходят code review, а из одного набора файлов создаются сайт, DOCX для согласования и PDF для публикации. Важно заранее ограничить используемые расширения и закрепить профиль сборки.

Учебные материалы удобно выпускать как HTML, раздаточный PDF и EPUB. Формулы, сноски и библиография остаются в одном исходном файле. Для презентации тот же текст приходится сокращать, но общие фрагменты можно включать на этапе сборки или генерировать из метаданных.

Научная работа использует citeproc, CSL и математическую разметку. Pandoc снимает значительную часть механической работы с цитатами, однако не проверяет научную корректность библиографических данных. Автор должен сверить имена, DOI, страницы, язык и требования журнала.

Корпоративные отчёты удобно собирать из данных и Markdown по расписанию. Таблицы генерирует сценарий, Pandoc применяет reference.docx и создаёт файл для редакторов. Для PDF используется отдельный профиль. Такой процесс уменьшает ручное копирование, но требует тестов на переполнение таблиц и отсутствие ресурсов.

Миграция контента между CMS и форматами разметки также подходит Pandoc, если исходные страницы доступны как статический HTML. После конвертации выполняют очистку классов, проверку внутренних ссылок и изображений. Для динамических компонентов пишут фильтр или отдельный экстрактор.

Как организовать проект

Разделите содержание и оформление. В каталоге source храните Markdown, в media — изображения, в styles — CSS, CSL и reference-документы, в filters — Lua, в defaults — профили сборки. Результаты помещайте в отдельный build, который можно удалить и создать заново.

Главный defaults-файл не должен ссылаться на абсолютный путь пользователя. Используйте относительные пути или подстановку каталога самого файла. В README проекта укажите одну команду сборки и список требуемых движков. Если PDF требует шрифты, перечислите точные семейства и способ проверки их наличия.

Добавьте небольшой контрольный документ со всеми элементами оформления. Он собирается быстрее книги и показывает, что после обновления не сломались заголовки, таблицы, код, цитаты, формулы и изображения. Скриншоты или эталонный PDF помогают заметить визуальные изменения.

Не храните секреты в metadata или командной строке: они могут попасть в историю shell, лог CI и свойства документа. Закрытые данные передавайте безопасным способом и удаляйте временные файлы. Фильтры не должны выводить содержимое окружения в отладочный журнал.

Перед выпуском очищайте build, запускайте сборку с нуля и проверяйте все ссылки. Успешная инкрементальная сборка может использовать старый файл, который уже не создаётся текущей конфигурацией. Чистый запуск выявляет такие зависимости.

Контроль качества результата

HTML проверяют валидатором, открывают без сети при заявленном автономном режиме, тестируют оглавление, внутренние ссылки, изображения и кодовые блоки. Если используется CSS, оценивают узкий экран и печать. Для непроверенного ввода дополнительно выполняют санитарную обработку.

DOCX открывают в целевой версии Word или совместимого редактора. Проверяют стили заголовков, автоматическое оглавление, нумерацию, подписи, таблицы, сноски, формулы, поля, колонтитулы и свойства документа. Важно включить отображение непечатаемых символов и убедиться, что разрывы созданы правильными элементами, а не пустыми абзацами.

PDF просматривают постранично и извлекают текст. Визуальный контроль ищет обрезанные строки, пустые глифы, переполненные таблицы, оторванные заголовки и изображения низкого качества. Извлечение текста подтверждает, что документ не превратился в набор картинок и поиск работает.

EPUB валидируют, проверяют навигацию и открывают в нескольких ридерах. Размер файла сравнивают с суммой ресурсов: неожиданно большой контейнер может содержать исходные изображения без оптимизации или встроенные шрифты. Обложка и метаданные должны отображаться в библиотеке ридера, а не только на первой странице.

PPTX проверяют в режиме показа и редактирования. Текст не должен выходить за заполнители, заметки — попадать на слайды, а изображения — искажаться. Если презентация предназначена для другого компьютера, убедитесь в доступности шрифтов или используйте безопасную замену.

Итоговый рабочий сценарий

Начните с семантически чистого исходного файла и явного reader. Сначала создайте простой целевой файл без пользовательского оформления и проверьте структуру. Затем подключите reference-документ или template, после него — библиографию, фильтры и дополнительные параметры. Такой порядок показывает, какой компонент изменил результат.

Все повторяемые опции перенесите в defaults, пути сделайте относительными, а требуемые ресурсы включите в проект. Зафиксируйте версии Pandoc, PDF-движка и критичных фильтров. Добавьте контрольный документ и чистую сборку в CI.

При ошибке не меняйте десяток параметров одновременно. Сведите пример к минимуму, посмотрите native AST, сохраните промежуточный формат и отдельно запустите writer или PDF-engine. Этот метод позволяет быстро определить, где потерялась структура или возникла проблема оформления.

Pandoc даёт наибольшую пользу не как разовая кнопка экспорта, а как прозрачный конвейер публикации: содержание остаётся в редактируемом текстовом виде, правила оформления хранятся отдельно, а каждый результат можно пересобрать одной командой. Границы программы становятся понятными заранее: готовый PDF правят другим инструментом, сложный визуальный макет проектируют в целевом редакторе, а Pandoc отвечает за проверяемое преобразование структуры между форматами.