Asciidoctor PDF превращает исходники AsciiDoc в готовые PDF-документы с оглавлением, закладками, перекрёстными ссылками, нумерацией страниц, подсветкой кода, таблицами и настраиваемым оформлением. Пользователь описывает структуру и содержание в текстовом файле, запускает конвертацию командой asciidoctor-pdf, а внешний вид задаёт атрибутами документа и YAML-темой — от формата страницы и шрифтов до обложки, колонтитулов и правил печати.

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

Основные настройки доступны на трёх уровнях. Разметка AsciiDoc отвечает за смысловую структуру, атрибуты документа меняют параметры конкретной сборки, а YAML-тема управляет типографикой и оформлением. Такой подход удобен для инструкций, технических регламентов, справочников, отчётов и книг, которые хранятся в системе контроля версий и регулярно пересобираются автоматически.

Как устроена работа с Asciidoctor PDF

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

Минимальный исходник начинается с заголовка документа, после которого идут абзацы и разделы. Заголовки первого уровня в теле обозначаются двумя знаками равенства, следующие уровни — тремя и более. Маркеры списков, блоки кода, таблицы и ссылки записываются компактными конструкциями AsciiDoc. Конвертер получает разобранную модель документа от процессора Asciidoctor и преобразует её в команды библиотеки Prawn. Поэтому многие правила языка AsciiDoc действуют одинаково при выводе в HTML и PDF, но параметры пагинации, колонтитулов, обложек и печати относятся именно к PDF-конвертеру.

Для первого запуска достаточно команды asciidoctor-pdf document.adoc. По умолчанию файл document.pdf появится в каталоге исходника. Имя можно изменить ключом -o, а каталог вывода — ключом -D. Если входных файлов несколько, команда обрабатывает их последовательно. При сборке в сценарии лучше указывать каталог явно, чтобы артефакты не смешивались с исходниками.

asciidoctor-pdf guide.adoc
asciidoctor-pdf -o handbook.pdf guide.adoc
asciidoctor-pdf -D build docs/*.adoc

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

Практический исходник обычно содержит заголовок, автора и набор атрибутов перед первым пустым абзацем. Эта область называется заголовком документа. Здесь удобно включить оглавление, подсветку кода, нумерацию разделов и воспроизводимую сборку. Атрибут reproducible убирает из результата значения, которые меняются от запуска к запуску, например текущую дату создания, поэтому двоичное сравнение сборок становится предсказуемее. Атрибут toc создаёт оглавление, sectnums включает номера разделов, а source-highlighter выбирает подсветчик.

= Руководство администратора
Иван Петров
:toc:
:sectnums:
:reproducible:
:source-highlighter: rouge

Краткое назначение документа.

== Установка

Текст раздела.

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

Не стоит выравнивать макет пробелами и пустыми строками. В PDF используются пропорциональные шрифты, а ширина строки зависит от темы, размера страницы и гарнитур. Для разрывов применяются явные конструкции: тройной знак меньше создаёт переход на новую страницу, а опции блоков управляют допустимостью переноса. Когда требуется удержать небольшой блок целиком, используется параметр unbreakable; если таблица или листинг должен свободно переходить на следующую страницу, полезна опция breakable.

Командная строка и параметры сборки

Команда asciidoctor-pdf является удобной оболочкой над обычным вызовом Asciidoctor с подключённым PDF-конвертером. Эквивалентная форма выглядит как asciidoctor -r asciidoctor-pdf -b pdf. Короткая команда уменьшает риск забыть подключение библиотеки или неверно задать backend, но остальные стандартные ключи Asciidoctor сохраняются. Через -a передаются атрибуты, через -r подключаются расширения, а -S задаёт базовый каталог исходников.

Атрибуты из командной строки подходят для параметров, которые меняются между сборками. Например, одна задача CI может выпускать экранную версию, а другая — печатную, не редактируя исходник. Запись -a media=print переключает правила печати, -a pdf-page-size=Letter меняет формат бумаги, -a pdf-page-layout=landscape выбирает альбомную ориентацию, а -a compress включает сжатие потоков PDF. Значение с восклицательным знаком снимает атрибут.

asciidoctor-pdf -a media=print -a pdf-page-size=A4 manual.adoc
asciidoctor-pdf --theme corporate -a compress manual.adoc
asciidoctor-pdf -r asciidoctor-diagram architecture.adoc

Пути следует задавать осмысленно. Тема, шрифты, изображения и подключаемые файлы разрешаются относительно разных базовых каталогов. Исходные изображения обычно ищутся относительно imagesdir, тема — относительно pdf-themesdir, а включаемые фрагменты — относительно каталога документа или значения, заданного для обработки. Если сборка работает в терминале, но падает в CI, первым делом сравнивают текущий рабочий каталог и значения этих атрибутов.

Оглавление, закладки и внутренняя навигация

Оглавление создаётся по структуре разделов. Атрибут toclevels ограничивает глубину: значение 2 включает разделы и подразделы, более высокое значение добавляет вложенные уровни. Для книги оглавление обычно начинается на отдельной странице; в статье его можно разместить в начале, в преамбуле либо в точке, где стоит макрос toc::[]. При ручном размещении важно учитывать объём: если после оглавления контент накладывается на первую страницу текста, увеличивают резерв страниц или меняют точку вставки.

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

Перекрёстные ссылки привязываются к идентификаторам. Явный идентификатор задаётся конструкцией [[install]] или атрибутом [#install] перед разделом. Затем запись <<install,раздел установки>> создаёт кликабельный переход и понятный текст. Если текст не задан, используется заголовок или значение reftext. Для стабильной документации лучше назначать идентификаторы вручную: автоматически полученные ID зависят от заголовка и меняются при его переименовании.

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

Темы YAML и принцип каскада

Оформление описывается YAML-файлом, имя которого обычно заканчивается на -theme.yml. Тема управляет цветами, шрифтами, полями, расстояниями, границами, фонами, колонтитулами и стилями отдельных элементов. Система напоминает CSS терминами и наследованием, но не является CSS: селекторы HTML и каскад браузера здесь не работают. Конвертер загружает ключи темы, преобразует их в плоскую карту и применяет при расчёте PDF.

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

extends: default
page:
  size: A4
  margin: [22mm, 18mm, 22mm, 18mm]
base:
  font-family: Noto Serif
  font-size: 10.5
heading:
  font-family: Noto Sans
  font-color: #24364B
link:
  font-color: #0B62A4

Тема подключается атрибутами pdf-theme и pdf-themesdir либо ключом --theme. Если указано короткое имя без расширения, конвертер добавляет суффикс -theme.yml. Файлы с расширением .yaml не подхватываются по этому правилу, поэтому безопаснее придерживаться .yml. Каталог шрифтов задаётся отдельно через pdf-fontsdir; в нём можно перечислить несколько путей.

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

Шрифты, кириллица и специальные символы

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

font:
  catalog:
    PT Serif:
      normal: PTSerif-Regular.ttf
      bold: PTSerif-Bold.ttf
      italic: PTSerif-Italic.ttf
      bold_italic: PTSerif-BoldItalic.ttf
  fallbacks:
    - Noto Sans
base:
  font-family: PT Serif

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

Шрифт для моноширинного текста задаётся отдельно. Он используется в листингах, литеральных блоках и некоторых технических подписях. У него должны присутствовать цифры в кружках, если применяются callout-метки. Для исходного кода важна одинаковая ширина знаков и различимость похожих символов: нуля и буквы O, единицы и строчной l. Слишком крупный кегль увеличивает переносы, а слишком мелкий ухудшает чтение печатной версии.

Если пользовательский шрифт вызывает ошибку TTFunk, файл проверяют и пересохраняют в FontForge. Проблемы часто связаны с повреждёнными таблицами, неподдерживаемым контейнером TTC или современными таблицами кернинга, которые библиотека обрабатывает не так, как настольный редактор. Рекомендуемый путь — конвертировать гарнитуру в TTF или OTF, сохранить традиционную таблицу kerning и повторить сборку на минимальном документе.

Автоматические переносы слов не включаются сами. Для них устанавливается дополнительная библиотека text-hyphen и задаётся атрибут hyphens. Язык документа должен быть указан корректно, иначе алгоритм применит неподходящие правила. В техническом тексте переносы проверяют особенно внимательно: имена команд, идентификаторы, адреса и пути не должны дробиться как обычные слова.

Размер страницы, поля и печатный режим

Формат страницы задаётся стандартным именем вроде A4, Letter или Legal либо парой размеров в теме. Ориентация может быть портретной или альбомной. Для отдельной большой таблицы нельзя штатно переключить размер страницы посреди обычного потока так же свободно, как в некоторых системах верстки; обычно таблицу упрощают, поворачивают весь документ, выносят в отдельный PDF и импортируют либо расширяют конвертер.

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

Атрибут media переключает сценарий вывода. В экранном режиме ссылки обычно отображаются как кликабельный текст без печати адреса. В печатном режиме можно вывести URI рядом с подписью, чтобы адрес не потерялся на бумаге. Атрибут show-link-uri позволяет принудительно включить или отключить такое поведение. Для документов с длинными адресами полезно скрыть URI и вынести список ресурсов в отдельный раздел, иначе строки разрушают набор.

Режим prepress формирует двусторонний макет: внутренние и внешние поля меняются местами на чётных и нечётных страницах, а страницы трактуются как verso и recto. Это важно для переплёта и размещения номера у внешнего края. При подготовке книги следует проверить, с какой физической страницы начинается основной счёт, где стоят пустые обороты и как размещаются части, главы и титульный лист.

Нумерация может иметь физическое и виртуальное значение. Вступительные страницы часто получают римские номера, а основная часть начинается с арабской единицы. Параметры темы определяют, с какого элемента запускается счёт и на каких страницах номер отображается. Если виртуальное начало изменено, расположение номера на recto и verso можно привязать к физической странице с помощью настройки folio placement.

Колонтитулы и текущие данные документа

Верхний и нижний колонтитулы задаются категориями header и footer. Каждый может иметь до трёх колонок: левую, центральную и правую. Для recto и verso допускаются разные значения, чтобы номер страницы всегда находился у внешнего края, а название главы — ближе к корешку. Колонтитул включается только при заданной высоте; одного текста без height недостаточно.

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

header:
  height: 18mm
  border-color: #D0D5DA
  border-width: 0.25
  recto:
    left:
      content: image:brand.png[pdfwidth=24mm]
    center:
      content: '{document-title}'
footer:
  height: 12mm
  recto:
    right:
      content: '{chapter-title} | *{page-number}*'
  verso:
    left:
      content: '*{page-number}* | {chapter-title}'

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

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

Изображения, SVG и диаграммы

Без дополнительных библиотек конвертер обрабатывает PNG, JPEG и SVG. Относительный путь в документе разрешается относительно imagesdir; если атрибут не задан, базой служит каталог исходного файла. Изображения, указанные в теме, ищутся относительно каталога темы, а не imagesdir. Такое разделение позволяет держать иллюстрации содержания отдельно от фирменных фонов и логотипов.

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

SVG переводится в нативные PDF-объекты. Корневой элемент должен содержать viewBox; отсутствие этой области просмотра приводит к обрезанию или неправильному масштабу. Фиксированные width и height в корне иногда создают лишнее пространство, особенно значение 100%. Размер безопаснее контролировать атрибутом макроса. Текст внутри SVG использует семейства, зарегистрированные в теме; неизвестный шрифт заменяется стандартным, который может не содержать кириллицу.

GIF, WebP, TIFF, BMP и чересстрочный PNG требуют prawn-gmagick. Дополнение использует GraphicsMagick и доступно для C Ruby на Linux и macOS, поскольку собирается с нативными расширениями. Помимо новых форматов оно ускоряет декодирование большого количества PNG. Если GraphicsMagick неверно определяет глубину конкретного PNG, интеграцию можно отключить для PNG модулем asciidoctor/pdf/nopngmagick или полностью модулем asciidoctor/pdf/nogmagick.

Удалённые изображения по умолчанию не читаются. Чтобы разрешить URI, атрибут allow-uri-read передают через CLI или API. Запись этого атрибута внутри документа не должна считаться доверенной: он относится к защищённым параметрам. В воспроизводимой сборке лучше скачивать ресурсы заранее и хранить рядом с исходниками, иначе результат зависит от сети, доступности сервера и изменения файла по прежнему адресу.

Asciidoctor Diagram подключается ключом -r asciidoctor-diagram. Расширение генерирует PNG или SVG из PlantUML, Graphviz и других поддерживаемых нотаций, а PDF-конвертер встраивает результат. Если входной и выходной каталоги различаются, интеграция передаёт абсолютный путь промежуточной картинки. Для SVG-диаграмм следует настроить шрифт генератора так, чтобы то же семейство было зарегистрировано в PDF-теме.

Листинги и подсветка синтаксиса

Исходный код оформляется блоком со стилем source и названием языка. Подсветка выполняется во время сборки, поэтому браузерные JavaScript-библиотеки здесь не подходят. Поддерживаются Rouge, Pygments и CodeRay; Rouge считается предпочтительным вариантом. Подсветчик устанавливается отдельно, после чего в заголовке задаётся :source-highlighter: rouge.

[source,ruby]
----
require 'asciidoctor-pdf'
Asciidoctor.convert_file 'guide.adoc', backend: 'pdf'
----

Цветовая схема подсветки выбирается атрибутом вроде rouge-style. Она взаимодействует с фоном и цветами темы: тёмная схема на светлом блоке или светлая на белом может сделать токены нечитаемыми. Перед выпуском печатной версии проверяют монохромную распечатку, потому что два различимых на экране оттенка серого могут сливаться.

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

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

Таблицы, списки, примечания и подписи

Таблица AsciiDoc описывает колонки и ячейки в текстовом виде. Конвертер рассчитывает ширины в пределах доступной области. Атрибут cols задаёт относительные доли, выравнивание и тип содержимого. Режим autowidth полезен для коротких таблиц, но в длинных строках может привести к узким или переполненным колонкам. Для справочника лучше явно определить пропорции и проверить самые длинные значения.

[cols="2,3,2",options="header"]
|===
|Параметр |Назначение |Пример
|pdf-theme |Тема оформления |corporate
|pdf-page-size |Формат страницы |A4
|media |Режим вывода |print
|===

Таблица может переноситься между страницами. Заголовок колонок повторяется, если это поддерживает конкретная структура. Опция unbreakable удерживает небольшую таблицу целиком, но для большой таблицы создаст пустое место или заставит блок перейти дальше. Опция breakable снимает защиту заголовка и позволяет начать блок в оставшемся пространстве. При сложной таблице с объединениями нужно проверить каждую границу страницы.

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

Примечания NOTE, TIP, WARNING, CAUTION и IMPORTANT выводятся как admonition-блоки. Они могут использовать текстовые метки или значки. В корпоративной теме важно не полагаться только на цвет: предупреждение должно отличаться подписью и формой, чтобы сохранять смысл при чёрно-белой печати. Для каждого типа можно настроить границу, фон, ширину колонки значка и внутренние отступы.

Подписи таблиц, изображений и листингов формируются из заголовка блока и последовательного номера. Текст метки локализуется атрибутами вроде table-caption и figure-caption. Если документ собирается на нескольких языках, эти значения задают в языковом файле атрибутов или передают из системы сборки, чтобы не редактировать тему.

Титульная страница, обложки и фон

Титульная страница включается автоматически для книги или атрибутом title-page для статьи. На ней размещаются название, автор, дата и сведения о выпуске документа, если они заданы в исходнике. Тема управляет положением, шрифтом, цветом и расстояниями каждого элемента. Если титульный лист не нужен, его отключают атрибутом notitle либо значением false в категории title-page.

Логотип добавляется атрибутом title-logo-image. Макрос изображения допускает ширину, выравнивание и положение сверху. Фоновое изображение титульной страницы задаётся отдельно. Для полноценной обложки можно использовать переднюю и заднюю фоновые страницы. Картинка масштабируется режимами, похожими на object-fit: contain помещает её целиком, cover заполняет лист с возможной обрезкой, fill растягивает по двум осям, а none сохраняет заданный размер.

Фон разрешается назначить всем страницам, только recto, только verso или отдельной ориентации. Передний слой page-foreground-image используется как водяной знак поверх содержимого. Водяной знак не должен мешать выделению текста и кликам по ссылкам. Для печати проверяют прозрачность и цветовой охват: насыщенный экранный фон расходует тонер и может снижать контраст мелкого текста.

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

Сборка книги из нескольких файлов

Большой документ удобнее делить на главы и подключать директивой include. Главный файл хранит заголовок, общие атрибуты и порядок модулей, а отдельные файлы — содержание разделов. Такой проект легче рецензировать и переводить. Включаемые файлы должны использовать уровни заголовков, согласованные с местом вставки; параметр leveloffset помогает сдвинуть уровень без переписывания каждого заголовка.

= Руководство
:doctype: book
:toc:
:imagesdir: images

include::chapters/intro.adoc[leveloffset=+1]
include::chapters/install.adoc[leveloffset=+1]
include::chapters/settings.adoc[leveloffset=+1]

Условные директивы ifdef, ifndef и ifeval позволяют собирать варианты из одного набора исходников. Например, атрибут edition включает разделы для администратора, пользователя или разработчика. Условия должны оставаться понятными: сложная сеть вложенных проверок затрудняет рецензирование. Полезно вынести наборы атрибутов в отдельные файлы и иметь команду сборки для каждого варианта.

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

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

Автоматизация, Bundler и воспроизводимость

Для проекта с постоянной сборкой зависимости фиксируют через Bundler. В Gemfile перечисляются Asciidoctor PDF, подсветчик, диаграммы и другие расширения, после чего bundle lock сохраняет разрешённые версии. Команда запускается как bundle exec asciidoctor-pdf, чтобы использовались именно зависимости проекта, а не случайные гемы из системного каталога.

gem 'asciidoctor-pdf'
gem 'rouge'
gem 'asciidoctor-diagram'

В репозиторий обычно помещают исходники, тему, шрифты с разрешённой лицензией, изображения, Gemfile и lock-файл. Готовый PDF можно хранить как релизный артефакт, но не обязательно добавлять после каждого изменения. CI выполняет установку зависимостей, сборку, проверку журналов и публикацию. Ошибки и предупреждения лучше считать значимыми: отсутствующая картинка иногда не останавливает команду, но оставляет пустое место в документе.

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

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

Использование через Ruby API

Конвертер можно вызывать из Ruby-кода. Сначала подключается asciidoctor-pdf, затем обычному API Asciidoctor передаётся backend pdf. Метод convert_file читает файл и записывает результат, а convert может принимать строку. Параметры API соответствуют ключам командной строки: атрибуты передаются хешем, каталог вывода — опцией, расширения регистрируются до конвертации.

require 'asciidoctor-pdf'

Asciidoctor.convert_file(
  'manual.adoc',
  backend: 'pdf',
  safe: :safe,
  to_dir: 'build',
  attributes: {
    'pdf-theme' => 'corporate',
    'pdf-themesdir' => 'theme'
  }
)

Когда PDF нужен в памяти, вывод направляют в StringIO. Это подходит для веб-приложения, фоновой задачи или теста, но нужно учитывать объём: большой документ целиком находится в памяти. Предпочтительно передать поток как to_file, чтобы процедура завершения конвертера выполнила очистку. Прямой вызов низкоуровневого render на объекте Prawn обходит часть завершающей логики.

Возвращаемый конвертер является объектом Prawn::Document, что позволяет расширить поведение, но связывает код с внутренними методами. Для устойчивой интеграции лучше использовать официальные расширения Asciidoctor и наследование конвертера только там, где темы недостаточно. Пользовательский класс может изменить отрисовку заголовков, добавить страницу лицензии, особый разделитель или дополнительные записи оглавления.

Интеграция с JVM, Maven и Gradle

В проектах Java конвертация выполняется через AsciidoctorJ PDF или плагины сборки. Смысловая модель и тема остаются теми же, но пути ресурсов могут находиться в classpath. Атрибут pdf-theme допускает путь с префиксом uri:classloader:, что позволяет упаковать тему и шрифты в JAR. При переносе примеров из Ruby-команды важно различать нативные гемы и JVM-зависимости.

Maven-плагин обычно запускает обработку на фазе подготовки пакета и складывает результат в target/generated-docs. Gradle решает ту же задачу отдельной задачей документации. В обоих случаях backend указывается как PDF, а атрибуты передаются в конфигурации. Преимущество интеграции — документ строится вместе с программой, поэтому описание API, схемы и примеры можно синхронизировать с исходным кодом.

Ошибки путей в JVM-проекте часто возникают из-за различия между каталогом проекта, каталогом исходного документа и classpath. Тему следует либо копировать в рабочий каталог задачи, либо ссылаться на ресурс classloader. Шрифты должны быть доступны конвертеру как реальные ресурсы, а изображения из документа — разрешаться относительно настроенного imagesdir. Проверка на отдельной машине выявляет неявные абсолютные пути.

Оптимизация размера и требования к PDF

Атрибут compress включает FlateDecode для потоков и уменьшает технический объём без изменения качества изображений. Это первый безопасный шаг. Если PDF остаётся большим, анализируют растровые иллюстрации: картинка 6000×4000 пикселей, показанная шириной 80 мм, всё равно может быть встроена почти целиком. Её следует заранее уменьшить до разумного разрешения и выбрать JPEG для фотографий, PNG для схем с резкими границами или SVG для векторной графики.

Глубокая оптимизация выполняется Ghostscript через RGhost либо отдельной утилитой HexaPDF. Атрибут optimize запускает интегрированный путь и допускает профили screen, ebook, printer и prepress. Можно запросить соответствие PDF/A или PDF/X. Эти режимы меняют обработку цветов, метаданных и совместимость, поэтому результат проверяют валидатором, который принят в конкретной организации или типографии.

Ghostscript должен быть доступен как команда gs. В Windows путь часто задаётся переменной окружения GS, потому что установщик помещает исполняемый файл под другим именем и не добавляет его в PATH. Если оптимизация выдаёт PDF с растеризованным текстом, пропавшими ссылками или проблемами прозрачности, не следует снижать версию PDF вслепую; лучше попробовать HexaPDF или отказаться от проблемного профиля.

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

HexaPDF умеет сжимать страницы и удалять недостижимые объекты, не пересчитывая изображения. Его лицензия AGPL должна быть совместима с процессом использования. Дополнительные возможности, включая парольную защиту, относятся к HexaPDF, а не к базовой функции Asciidoctor PDF. Это различие важно при описании возможностей конечному пользователю и при развёртывании на сервере.

Безопасность ресурсов и доверие к исходнику

AsciiDoc-документ может включать другие файлы, читать изображения и подключать расширения. Поэтому сборка чужого исходника эквивалентна обработке активного проекта, а не открытию безобидного текста. Уровень safe mode ограничивает доступ к файловой системе. Удалённые URI запрещены, пока доверенный запускающий процесс не передаст allow-uri-read. Расширения Ruby выполняют код в процессе и должны устанавливаться только от проверенного поставщика.

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

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

Производительность на больших документах

Время сборки складывается из разбора AsciiDoc, вычисления макета, декодирования изображений, рендеринга SVG, подсветки кода и оптимизации. В книге с сотнями PNG наиболее дорогой частью часто становится распаковка изображений в Ruby. Prawn Gmagick переносит эту работу в GraphicsMagick и способен заметно ускорить проект, но требует нативной установки и не поддерживается одинаково во всех средах.

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

Сложные таблицы и защита от разрыва требуют пробного расчёта. Конвертер иногда выполняет dry run, чтобы определить, помещается ли заголовок или блок на странице. Чрезмерное количество unbreakable-блоков увеличивает работу и создаёт пустоты. Для длинного листинга или таблицы лучше разрешить перенос, чем заставлять систему многократно искать страницу, где элемент всё равно не помещается целиком.

Профилирование начинают с отключения оптимизации и диаграмм. Затем возвращают компоненты по одному. Если сборка медленна только на одном файле, создают минимальный пример из проблемного раздела. Отдельно сравнивают время с PNG и JPEG, со стандартной и пользовательской темой, с подсветкой и без неё. Такой подход быстрее, чем менять несколько параметров одновременно.

Типичные ошибки и способы исправления

Команда не найдена после установки

Проверяют gem which asciidoctor-pdf и command -v asciidoctor-pdf. Если библиотека установлена, а исполняемый файл отсутствует в PATH, проблема относится к окружению Ruby. Системный Ruby часто размещает гемы в защищённом каталоге. Менеджер версий Ruby или Bundler устанавливает зависимости в пользовательской области и даёт предсказуемый путь. В проекте команду запускают через bundle exec.

Нет прав на каталог gems

Ошибка Gem::FilePermissionError означает попытку записи в системный каталог. Не следует решать её постоянным запуском sudo: это смешивает владельцев файлов и усложняет обновление. Устанавливают пользовательский Ruby через менеджер версий либо настраивают отдельный GEM_HOME, после чего повторяют установку обычным пользователем.

Изображение не найдено

Сначала проверяют фактический путь, регистр букв и значение imagesdir. В Linux имена чувствительны к регистру, поэтому файл Diagram.PNG не совпадает с diagram.png. Для картинки из темы проверяют pdf-themesdir, а не imagesdir. В CI печатают текущий каталог и используют пути, вычисленные от docdir.

Удалённая картинка пропущена

Предупреждение о запрете remote image устраняется передачей -a allow-uri-read, но только когда сетевой ресурс доверен. Для стабильной публикации файл лучше добавить в репозиторий. Если URI находится внутри SVG, разрешение также требуется, а вложенное изображение должно иметь ширину и высоту.

SVG обрезан или пуст

Проверяют наличие viewBox, удаляют проблемные width и height из корневого элемента и задают размер через pdfwidth. Если пропал текст, регистрируют семейство SVG в теме или меняют шрифт в генераторе диаграммы. Сложные фильтры и возможности SVG, которые не поддерживает prawn-svg, заменяют более простыми объектами либо предварительно конвертируют файл в PDF или PNG.

Кириллица отображается квадратами

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

Оглавление пустое или слишком короткое

Проверяют наличие разделов, значение toclevels и тип документа. Нулевое или отрицательное значение не предназначено для полного отключения всех уровней в любой структуре. Чтобы убрать оглавление, снимают атрибут toc. Если нужен один уровень, задают значение 1 и проверяют, какой уровень считается главой в книге.

Колонтитул перекрывает текст

Высота header или footer больше поля страницы. Увеличивают соответствующее поле либо уменьшают высоту и размеры содержимого. Логотипу задают ограниченную ширину. Отдельно проверяют страницы с альбомной ориентацией и импортированные страницы, где геометрия отличается.

Листинг выходит за правый край

Уменьшают шрифт кода, включают перенос, сокращают строки или меняют структуру примера. Для команд удобно использовать обратную косую черту и переносы, для JSON — форматирование с отступами. Горизонтальное масштабирование текста ухудшает читаемость и обычно не требуется.

Оптимизация не запускается

Проверяют установку rghost и доступность Ghostscript. В Windows задают путь к консольному исполняемому файлу через переменную GS. Если цель — только уменьшить служебные потоки, достаточно compress без Ghostscript. Для уже созданного PDF можно использовать HexaPDF, учитывая его лицензию.

Установка и рабочее окружение

Для запуска требуется Ruby 2.7 или новее либо JRuby 9.2 или новее. Перед установкой проверяют командой ruby -v, какой интерпретатор фактически доступен в текущем терминале. На машине может быть несколько Ruby, поэтому вывод версии и путь command -v ruby важнее записи в меню программ. Системная кодировка должна быть UTF-8: иначе русские имена файлов, содержимое подключаемых модулей и сообщения журнала могут обрабатываться непредсказуемо.

Основная установка выполняется командой gem install asciidoctor-pdf. Менеджер RubyGems автоматически добавляет обязательные зависимости: Asciidoctor, Prawn, обработчики SVG и таблиц, библиотеку шрифтов и другие компоненты, согласованные с пакетом. После установки проверяют asciidoctor-pdf -v, затем создают короткий тестовый файл и собирают его. Проверка реальной конвертацией надёжнее простого вывода номера, потому что выявляет проблемы загрузки шрифтов и зависимостей.

На macOS и Linux не рекомендуется устанавливать гемы в системный Ruby с правами администратора. Менеджер версий Ruby, Bundler или пользовательский GEM_HOME позволяют отделить инструменты документации от компонентов операционной системы. В Windows удобно использовать полноценную сборку Ruby с Development Kit, если планируются гемы с нативными расширениями. Сам базовый конвертер не требует визуальной оболочки, но дополнительные форматы изображений могут потребовать GraphicsMagick.

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

Компонент	Когда нужен	Что проверить
Ruby или JRuby	Всегда	Версию, UTF-8 и путь исполняемого файла
Rouge	Цветные листинги	Установку гема и атрибут source-highlighter
text-hyphen	Автоматические переносы	Язык документа и качество переносов
GraphicsMagick и prawn-gmagick	GIF, WebP, TIFF, BMP и ускорение PNG	Поддерживаемую систему и нативную сборку
Ghostscript или HexaPDF	Дополнительная оптимизация	Путь к команде, профиль качества и итоговую совместимость

Структурные элементы книги

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

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

Предисловие без видимого заголовка можно включить в оглавление через preface-title и опцию notitle на первом блоке. Это полезно, когда типографический макет требует начать текст без крупного слова Предисловие, но навигация должна остаться полной. Похожий приём применяют к импортированной справочной карте.

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

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

Сноски, ссылки и адреса

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

Внешние ссылки остаются кликабельными, если просмотрщик поддерживает действия PDF. В экранном режиме это удобно, но при печати адрес может исчезнуть. Параметры media и show-link-uri определяют, будет ли URI напечатан после подписи. Для длинных адресов автоматический вывод часто портит строку; тогда используют короткое осмысленное имя, QR-код как локальное изображение или отдельный перечень ресурсов.

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

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

Роли и точечное оформление

Пользовательская роль назначается блоку или фразе через атрибут class-подобного вида. В теме категория role задаёт цвет, начертание, фон или другие поддерживаемые свойства. Роли позволяют выделить термин, команду, устаревший фрагмент или важный абзац без жёсткого оформления в содержании. Имя роли должно описывать смысл, например kbd или changed, а не конкретный цвет red.

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

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

Разрывы страниц и защита от висячих элементов

Конвертер старается не оставлять заголовок раздела один внизу страницы. Он оценивает минимальное место после заголовка и при необходимости переносит его вместе со следующим содержимым. Настройка heading-min-height-after управляет требованием, а значение auto позволяет оценить фактический блок. В редких случаях заголовок можно сделать breakable, если пустое место важнее защиты от висячей строки.

Опции breakable и unbreakable применяются к блокам с осторожностью. Unbreakable запускает пробную отрисовку, чтобы узнать высоту. Если блок больше страницы, удержать его целиком невозможно; результатом могут быть лишние вычисления и неудобные разрывы. Длинные таблицы, листинги и sidebars обычно должны быть переносимыми. Небольшая подпись с изображением, короткое предупреждение или компактная таблица могут выигрывать от удержания.

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

Непредвиденная пустая страница в prepress может быть результатом правила начала главы с recto. Это не ошибка: пустой verso сохраняет разворот. Колонтитул на такой странице можно отключить, если тема или расширение помечает её как пустую. Перед удалением страницы следует понять требования печати и переплёта.

Многостолбцовый текст и ограничения макета

Для article и manpage тело документа может выводиться в несколько колонок через ключи page-columns и page-column-gap. Заголовок документа и оглавление остаются вне колонок. Такой режим подходит для краткого справочника, памятки и бюллетеня, но не для каждой технической книги: таблицы, длинный код и широкие изображения быстро сталкиваются с нехваткой ширины.

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

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

Расширение конвертера

Когда возможностей YAML недостаточно, создают Ruby-класс, наследующий зарегистрированный PDF-конвертер. Можно переопределить обработчик конкретного узла: тематического разрыва, абзаца, таблицы, изображения или заголовка. Другой путь — переопределить высокоуровневый этап, например создание титульной страницы или оглавления. Класс подключается ключом -r до обработки документа.

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

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

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

Контроль качества готового PDF

Проверка не ограничивается открытием первой страницы. Просматривают титульный лист, оглавление, первую и последнюю главу, страницы с таблицами, кодом, сносками, SVG, кириллицей и редкими символами. Отдельно проверяют recto и verso, начало нумерации, закладки и внутренние ссылки. Поиск текста должен находить слова, а копирование не должно превращать строки в набор изображений.

Автоматическая проверка может убедиться, что PDF существует, имеет ненулевой размер и ожидаемое число страниц, а журнал не содержит WARNING или ERROR. Инструменты анализа PDF извлекают метаданные, список шрифтов и размер страниц. Для профиля PDF/A или PDF/X применяют специализированный валидатор; одно имя профиля в команде не заменяет проверку.

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

Доступность PDF требует отдельной оценки. Наличие семантической AsciiDoc-разметки не гарантирует полноценный tagged PDF, порядок чтения и совместимость со скринридером. Если норматив требует PDF/UA или детальной разметки доступности, необходимо проверить возможности цепочки и, возможно, применить другой генератор или постобработку. Не следует обещать соответствие только потому, что исходник структурирован.

Практические сценарии

Техническая инструкция с регулярными релизами

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

Печатное руководство в фирменном стиле

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

Справочник API с большим количеством кода

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

Единая база для нескольких вариантов

Общие главы подключаются include, а различия управляются атрибутами и условиями. Каждому варианту соответствует отдельная команда или задача сборки. Тема может наследоваться от общей и менять логотип, палитру и титульную страницу. CI собирает все варианты и проверяет, что ни один условный блок не оставил пустой раздел.

Одностраничная памятка

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

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

Программа	Лучше подходит для	Главное ограничение
Asciidoctor PDF	Технических книг и инструкций из AsciiDoc с темами, оглавлением и автоматической сборкой	Нет визуального редактирования страниц
Pandoc	Конвертации между множеством текстовых форматов и построения цепочек через LaTeX или другие PDF-движки	Итоговый макет зависит от выбранного движка и шаблона
WeasyPrint	Преобразования HTML и CSS в PDF с веб-подобной моделью оформления	Исходник нужно подготовить как HTML и CSS
Typst	Программируемой вёрстки статей, отчётов и научных материалов с быстрым предпросмотром	Использует собственный язык разметки
wkhtmltopdf	Сохранения существующих HTML-страниц и отчётов через движок WebKit	Современный CSS поддерживается неполно
PDF Commander	Ручного редактирования, объединения и оформления уже готовых PDF-файлов	Не строит книги из AsciiDoc

Asciidoctor PDF стоит выбирать, когда исходником является AsciiDoc и документ должен регулярно собираться одинаково в автоматическом процессе. Pandoc полезнее при большом числе входных форматов, WeasyPrint — когда дизайн уже описан HTML и CSS, Typst — когда требуется более свободная программируемая вёрстка, а wkhtmltopdf — для сохранения существующего веб-отчёта. PDF Commander решает другую практическую задачу: он удобен после генерации, если нужно вручную поправить готовый PDF, переставить страницы или объединить его с другими файлами.

Ограничения, которые важно учитывать заранее

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

Входной формат — AsciiDoc. Документы Word, готовые PDF и произвольный HTML не становятся редактируемым AsciiDoc автоматически. Импорт PDF используется для вставки страниц, а не для разбора и изменения их содержимого. Если исходник живёт в DOCX и редактируется авторами через офисный интерфейс, сначала нужно изменить рабочий процесс или выбрать конвертер, ориентированный на офисные форматы.

Расширенные возможности зависят от дополнительных компонентов. Подсветка требует отдельного гема, автоматические переносы — text-hyphen, расширенные растровые форматы — GraphicsMagick и prawn-gmagick, глубокая оптимизация — Ghostscript или HexaPDF, диаграммы — соответствующее расширение и движки. Эти зависимости следует фиксировать и устанавливать в сборочном окружении.

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

Рекомендуемая последовательность настройки

1. Соберите минимальный документ с темой по умолчанию и убедитесь, что кириллица, изображения и код отображаются корректно.
2. Зафиксируйте зависимости через Bundler и добавьте команду сборки в проект.
3. Разделите содержание на модули, назначьте стабильные идентификаторы разделам и включите оглавление.
4. Создайте дочернюю YAML-тему, меняя сначала шрифты и геометрию, затем цвета и декоративные элементы.
5. Настройте колонтитулы, титульную страницу и режим печати, проверяя recto и verso.
6. Оптимизируйте исходные изображения и только затем подключайте внешний оптимизатор PDF.
7. Добавьте проверку предупреждений, визуальную регрессию ключевых страниц и чистую сборку в CI.

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

Итоговый рабочий подход

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

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