Vivliostyle CLI: где скачать и как пользоваться

Vivliostyle CLI: преобразование HTML и Markdown в PDF

Vivliostyle CLI нужен тем, кто собирает PDF как воспроизводимый проект из Markdown, HTML и CSS, а не правит готовые страницы вручную. На Xeon Live можно скачать Vivliostyle CLI бесплатно и свериться с базовым описанием программы; ниже разберём рабочий процесс от первой команды до многофайловой публикации, предпросмотра и автоматической сборки.

Что представляет собой Vivliostyle CLI и для каких задач он нужен

Vivliostyle CLI — командный инструмент для книжной и документной верстки на базе веб-технологий. Исходником служит Markdown, HTML, публикационный манифест или EPUB, а оформление задаётся CSS и параметрами проекта. Важное отличие от обычного PDF-редактора в том, что результат каждый раз строится заново из мастер-файлов. Такой подход особенно удобен для технической документации, методичек, отчётов, электронных книг и регулярно обновляемых материалов, где текст живёт в Git, а выпуск должен повторяться без ручной переклейки страниц.

Где программа сильна и где её возможности заканчиваются

PDF, собранный Vivliostyle CLI
Готовый PDF — финальная точка конвейера, но не место, где вносят основные правки.

Сильная сторона Vivliostyle CLI — управление структурой и типографикой через текстовые файлы. Можно хранить главы отдельно, менять тему без переписывания рукописи, задавать формат листа, поля, колонтитулы, счётчики, оглавление и обложку, а затем выпускать один и тот же материал в PDF, EPUB или WebPub там, где это допускает тип входа. Это близко к сборке сайта или приложения: важен не отдельный экспортированный файл, а вся цепочка исходников, зависимостей и конфигурации.

Vivliostyle CLI не предназначен для OCR, ручного редактирования чужого PDF, удаления объектов на отдельной странице, заполнения форм или косметической правки скана. Для таких задач нужен редактор готовых PDF. Если же источник существует в HTML или Markdown и документ меняется регулярно, пересборка даёт больше контроля: правка одной строки остаётся в исходнике, а все страницы, оглавление и ссылки пересчитываются автоматически. Для общего понимания формата полезно держать под рукой разбор формата PDF на Xeon Live.

  • Подходит для книг, руководств и регламентов, где текст разбит на главы и регулярно обновляется.
  • Удобен для документации из репозитория, когда изменения надо видеть как текстовый diff, а выпуск повторять командой.
  • Полезен для отчётов, которые формируются из HTML-шаблона и данных, а затем одинаково собираются локально и в CI.
  • Не заменяет визуальную программу допечатной подготовки, когда требуется вручную двигать отдельные объекты мышью.
  • Не заменяет PDF-редактор для исправления чужого готового файла без исходников.

Рабочая среда: терминал, структура проекта и Vivliostyle Viewer

У Vivliostyle CLI нет отдельного настольного окна с холстом. Рабочая среда складывается из терминала, редактора кода, файлов проекта и браузерного Vivliostyle Viewer. Такая схема сначала кажется непривычной тем, кто пришёл из DTP-программ, но быстро становится логичной: рукопись отвечает за содержание, CSS — за вид, конфигурация — за порядок и выпуск, Viewer — за визуальную проверку пагинации.

Терминал и файлы проекта

Структура проекта Vivliostyle CLI
Типичный проект хранит рукопись, конфигурацию, package.json и зависимости рядом.

В терминале выполняются команды создания проекта, предпросмотра и сборки. В корне обычно лежат package.json, файл блокировки зависимостей и vivliostyle.config.js; главы удобно хранить в src или manuscripts, изображения — в assets, CSS — в styles. Такой порядок не навязан программой, но снижает число ошибок с относительными путями. При запуске из другого каталога один и тот же путь к картинке или шрифту может разрешаться иначе, поэтому рабочую папку лучше считать частью процедуры выпуска.

Для совместной работы полезно ставить Vivliostyle CLI в сам проект, а не только глобально. Тогда версия фиксируется зависимостями, а запуск идёт через npx или npm scripts. Это уменьшает риск, что у автора и на сервере установлены разные выпуски CLI. Отдельный workspaceDir удобно выделить под промежуточные HTML: тогда сгенерированные файлы не смешиваются с рукописью и легко удаляются перед чистой сборкой.

Vivliostyle Viewer как основной экран проверки

Vivliostyle Viewer с обложкой публикации
Viewer показывает уже разбитую на страницы публикацию, включая обложку.

Команда preview запускает локальный сервер и открывает Viewer в браузере. Здесь видно то, чего не показывает редактор исходника: реальные границы страниц, пустые листы, положение иллюстраций, колонтитулы, развороты и результат переноса текста. Панель Viewer позволяет переходить между страницами, менять масштаб и режим просмотра. Для длинного документа логично проверять не всё подряд, а заранее выбранные контрольные места: начало каждой главы, страницу с широкой таблицей, крупную иллюстрацию, сноски, последний разворот и оглавление.

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

Первый PDF из Markdown или HTML: пошаговый рабочий сценарий

Начинать лучше с минимального файла и только после успешной сборки добавлять тему, свои шрифты, оглавление и сложную конфигурацию. Так проще отделить проблему среды от ошибки в CSS или структуре публикации. Текущая документация Vivliostyle CLI требует Node.js 22.12.0 или новее; перед установкой проверьте версию Node, затем поставьте пакет и убедитесь, что команда отвечает на help.

Страница VFM после сборки Vivliostyle CLI
Минимальный VFM-файл после преобразования уже получает полноценную страничную верстку.

Сборка Markdown/VFM в PDF

VFM с кодом и сносками в Vivliostyle Viewer
Viewer показывает результат VFM с кодом, сносками и семантическими блоками.
  1. Шаг 1. Создайте отдельную папку проекта и откройте её в терминале. Выполните npm init -y, затем установите зависимость командой npm install @vivliostyle/cli. Проектная установка предпочтительна для повторяемой сборки, потому что версия фиксируется в package.json и lock-файле.
  2. Шаг 2. Создайте manuscript.md и добавьте короткий документ с заголовком первого уровня, несколькими абзацами, списком и одной ссылкой. Сначала не подключайте сложный CSS: задача этого шага — проверить преобразование VFM и работу движка.
  3. Шаг 3. Запустите npx vivliostyle preview manuscript.md. В браузере должен открыться Viewer с разбитым на страницы текстом. Проверьте, что заголовок не обрезан, список отображается целиком, а переход между страницами работает.
  4. Шаг 4. Соберите файл командой npx vivliostyle build manuscript.md -o book.pdf. Для A4 добавьте -s A4. После завершения откройте book.pdf обычным просмотрщиком и сравните первую, среднюю и последнюю страницу с Viewer.
  5. Шаг 5. Добавьте изображение относительным путём и повторите preview. Если картинка пропала, проверьте регистр имени файла и фактическое расположение ресурса относительно рукописи. На Linux различие Cover.png и cover.png существенно.
  6. Шаг 6. Только после стабильной базовой сборки вынесите стили в отдельный CSS и подключите его через --style styles/print.css или конфигурацию. Это позволит сразу понять, относится ли новый дефект к содержанию или к оформлению.

VFM сохраняет привычную логику Markdown, но ориентирован на публикации. В нём доступны конструкции для сносок, подписей, фрагментов HTML и другой семантики, которая затем превращается в HTML и участвует в пагинации. При сложном оформлении полезно посмотреть фактический HTML, который получился из конкретной конструкции, и уже по нему строить CSS-селекторы. Это надёжнее, чем подбирать селектор по догадке.

Сборка готового HTML в PDF

Для HTML процедура ещё короче. Подготовьте index.html с корректной структурой head/body и подключённым CSS. Выполните npx vivliostyle preview index.html, а после проверки — npx vivliostyle build index.html -o output.pdf. Если в HTML используются локальные изображения, шрифты и таблицы стилей, убедитесь, что они доступны из рабочей папки. Для веб-страницы с внешними ресурсами лучше сначала сделать статическую копию, чтобы выпуск не зависел от авторизации, динамических данных или изменяющихся сетевых файлов.

Отдельный практический сценарий — преобразование уже существующей HTML-страницы. Vivliostyle CLI умеет принимать и веб-адрес, однако для воспроизводимого выпуска предпочтительнее локальный набор HTML/CSS/assets. Тогда редакция контролирует исходник, шрифты и изображения, а повторная сборка через месяц не зависит от чужого сервера. На Xeon Live есть отдельная инструкция по преобразованию HTML в PDF, где рассмотрены и другие способы для разных платформ.

Многофайловая публикация: config, порядок глав и несколько выходов

Одиночная команда удобна для статьи, но книга или руководство быстро перерастают один файл. Тогда центр проекта — vivliostyle.config.js. Его можно создать через init или получить вместе с новым проектом, созданным через npm create book@latest. Конфигурация фиксирует метаданные, последовательность entry, тему, размер, оглавление, обложку, рабочую папку и output.

Как собрать книгу из нескольких глав

Конфигурационный файл Vivliostyle CLI
Конфигурация объединяет метаданные, формат листа, тему и порядок глав.
  1. Шаг 1. Разделите рукопись на логические файлы, например 01-intro.md, 02-workflow.md и 03-reference.md. Имена с числовыми префиксами удобны для навигации, но итоговый порядок всё равно должен задаваться явно в entry.
  2. Шаг 2. Создайте vivliostyle.config.js и задайте title, author и language. Для русскоязычного материала укажите языковой код ru, чтобы HTML получал корректный lang и типографические механизмы имели верный контекст.
  3. Шаг 3. В entry перечислите главы в точном порядке чтения. Для отдельной главы можно использовать объект с path, title и собственной theme. Не полагайтесь на алфавитный порядок каталога: явный массив легче проверить при рецензировании.
  4. Шаг 4. Добавьте workspaceDir, например .vivliostyle, чтобы промежуточные HTML не лежали рядом с рукописью. После этого запустите npx vivliostyle preview без имени файла — CLI возьмёт конфигурацию проекта.
  5. Шаг 5. Пройдите публикацию по структуре: титул, оглавление, главы, приложения. Убедитесь, что первая страница каждой главы соответствует задуманному порядку и что относительные изображения открываются после преобразования Markdown.
  6. Шаг 6. Соберите npx vivliostyle build и проверьте имя выходного файла. Для командной работы зафиксируйте package-lock.json, pnpm-lock.yaml или yarn.lock вместе с конфигурацией.

Несколько выходных форматов из одного проекта

Разворот Vivliostyle Viewer с иллюстрациями
Один и тот же структурированный материал можно проверять как разворот перед разными типами выпуска.

Поле output принимает строку, объект или массив. Это позволяет описать, например, PDF и WebPub в одной конфигурации. Для EPUB и WebPub нужен подходящий вход: Markdown, HTML, webbook или publication manifest; если исходником служит готовый EPUB/OPF, поддерживается преобразование в PDF, но не повторная упаковка в новый EPUB. Поэтому форматную стратегию лучше выбрать до начала верстки, а не в самом конце.

  1. Шаг 1. Оставьте общую семантику в HTML/VFM и избегайте оформления, которое существует только ради фиксированного листа.
  2. Шаг 2. Для PDF задайте page size, поля, колонтитулы и при необходимости печатные метки. Для электронных форматов не переносите эти правила механически.
  3. Шаг 3. В output добавьте отдельные объекты с path и format. После сборки откройте каждый результат своим типичным просмотрщиком, а не оценивайте EPUB только по PDF.
  4. Шаг 4. Проверьте порядок чтения, альтернативные тексты изображений, заголовки и навигацию в электронном выпуске. Фиксированная страница может скрыть структурную проблему, которая сразу проявится в ридере.
  5. Шаг 5. Храните выходы вне каталога исходников. Перед повторным выпуском очищайте старые артефакты, чтобы не принять файл от предыдущей успешной сборки за новый.

CSS для печатной страницы: темы, поля, колонтитулы и разрывы

В Vivliostyle CLI оформление строится теми же принципами, что и веб-страница, но поверх обычного CSS добавляется модель paged media. Тема задаёт базовую типографику, авторский CSS уточняет конкретное издание, а @page управляет размером листа и областями страницы. Такой слой лучше развивать постепенно: сначала типографика потока, затем формат листа, затем колонтитулы и только после этого сложные разрывы.

Тема и дополнительный CSS

Области полей CSS Paged Media
CSS Paged Media предоставляет области по краям листа для номеров и бегущих колонтитулов.

Готовую Vivliostyle Theme можно подключить параметром -T/--theme или полем theme в конфигурации. Дополнительный авторский файл подключается через --style, а пользовательский — через --user-style. Для постоянной верстки практичнее хранить все изменения в файлах, а не передавать длинный CSS прямо в командной строке: так изменения рецензируются, сравниваются и одинаково применяются в CI.

  1. Шаг 1. Подключите одну тему и выполните preview без собственных переопределений. Зафиксируйте, как выглядят заголовки, абзацы, списки, таблицы и код.
  2. Шаг 2. Создайте styles/print.css и подключите через --style. Начните с базовых параметров body, заголовков и изображений; после каждого небольшого блока правил обновляйте Viewer.
  3. Шаг 3. Если правило не сработало, откройте сгенерированный HTML и проверьте реальную структуру элемента. Затем сравните специфичность и порядок каскада. Массовое добавление !important обычно скрывает причину конфликта.
  4. Шаг 4. Шрифты подключайте через @font-face из контролируемого каталога. После замены гарнитуры обязательно пересмотрите пагинацию: другой шрифт меняет длину строк, высоту абзацев и номера страниц.
  5. Шаг 5. Проверяйте крайние случаи отдельно: длинную строку кода, широкую таблицу, крупную иллюстрацию, длинную сноску и заголовок, который едва помещается в одну строку.

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

Размер можно задать параметром -s/--size: документация перечисляет A5, A4, A3, B5, B4, JIS-B5, JIS-B4, letter, legal и ledger, а также произвольную пару размеров. Для стабильного проекта формат лучше вынести в CSS через @page или конфигурацию. Поля страницы задаются в @page, а не margin у body: это разные уровни модели.

  1. Шаг 1. Для черновика задайте -s A4 и убедитесь, что весь контент помещается без горизонтального переполнения.
  2. Шаг 2. Перенесите размер и поля в @page. Для зеркального книжного разворота используйте :left и :right, чтобы внутреннее и внешнее поле менялись местами.
  3. Шаг 3. Если нужен печатный выпуск, включите -m/--crop-marks. При необходимости добавьте --bleed и --crop-offset в соответствии с требованиями типографии.
  4. Шаг 4. Проверьте, что фоновые изображения действительно доходят до зоны вылета, а важный текст не приближается к линии реза. Само наличие меток не исправляет геометрию макета.
  5. Шаг 5. Откройте итоговый PDF средством, которое показывает размеры и боксы страницы. Сравните trim size с заданным форматом и только после этого передавайте файл дальше.

Колонтитулы, счётчики и управляемые разрывы

Нумерация страниц в Vivliostyle Viewer
Viewer помогает контролировать нумерацию и положение заголовков на развороте.

Номер страницы обычно выводится в margin box через counter(page). Для бегущего заголовка значение главы можно захватить string-set и вывести функцией string(). Сложность появляется не в синтаксисе, а в правилах исключений: обложка, титул и начало главы часто не должны показывать те же элементы, что обычная текстовая страница.

  1. Шаг 1. Добавьте номер страницы в @bottom-center и проверьте пять последовательных страниц, включая начало новой главы.
  2. Шаг 2. Настройте отдельное правило для первой страницы главы, чтобы не дублировать крупный заголовок в колонтитуле.
  3. Шаг 3. Для названия текущей главы примените string-set к заголовку и выведите строку в верхней области страницы. Перелистайте границу между двумя главами и проверьте момент смены значения.
  4. Шаг 4. Используйте break-before и break-after только там, где разрыв действительно семантически нужен. break-inside: avoid оставляйте для сравнительно небольших связанных блоков, иначе большой элемент способен создать огромную пустую зону.
  5. Шаг 5. После любой правки шрифта, межстрочного интервала или размеров изображения снова проверьте оглавление и целевые номера: они зависят от полной пагинации.

Предпросмотр, оглавление, обложка и финальный экспорт

После того как содержание и CSS собраны, рабочий цикл становится повторяющимся: изменить исходник, открыть preview, проверить критические страницы, выполнить build, проверить готовый файл. На этом этапе важны не новые эффекты, а дисциплина контроля. Viewer должен использовать те же входы и стили, что финальная сборка.

Как проверять публикацию в Viewer

Vivliostyle Viewer с текстовой страницей
Текстовая страница в Viewer позволяет оценить реальные переносы и длину блоков до экспорта.

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

  1. Шаг 1. Запустите npx vivliostyle preview из корня проекта и дождитесь полной пагинации.
  2. Шаг 2. Перейдите к титулу, оглавлению, первой странице каждой главы и последней странице. Проверьте, что пустые листы появляются только там, где они задуманы правилами разворота.
  3. Шаг 3. Откройте страницу с самой широкой таблицей и страницу с самым большим изображением. Ищите выход за поле, обрезанные подписи и пустоты, вызванные запретами разрыва.
  4. Шаг 4. Проверьте сноски, внутренние ссылки и несколько внешних ссылок. Для навигации между главами особенно важны устойчивые id после преобразования Markdown.
  5. Шаг 5. Для быстрой локальной правки разрешён --quick, но перед финальным build снова откройте обычный режим. Сравнивать номера страниц из quick с окончательным PDF бессмысленно.
  6. Шаг 6. После сборки откройте PDF отдельно от Viewer и проверьте выбор текста, переходы по оглавлению и свойства документа. Viewer подтверждает верстку, но не заменяет проверку финального контейнера.

Оглавление и навигация без ручной нумерации

Поле toc: true создаёт HTML-страницу оглавления. Объект toc позволяет менять имя файла, заголовок и sectionDepth от 1 до 6. Если оглавление должно стоять не первым, в entry используется служебный элемент с rel: contents. Для собственного шаблона готовят HTML с nav role="doc-toc", куда CLI вставляет пункты. Печатные номера должны зависеть от полной пагинации, а не быть набраны вручную в Markdown.

Базовое оглавление Vivliostyle Viewer
Оглавление верхнего уровня в Viewer.
Вложенное оглавление Vivliostyle Viewer
Оглавление с вложенными разделами.
Оглавление в PDF, собранном Vivliostyle CLI
Проверка оглавления и номеров уже в итоговом PDF.
  1. Шаг 1. Включите toc: true и соберите короткую книгу из трёх глав. Проверьте, что каждая глава появилась в оглавлении ровно один раз.
  2. Шаг 2. Увеличьте sectionDepth на один уровень и оцените, не стало ли оглавление перегруженным. Включать все H1–H6 обычно не нужно.
  3. Шаг 3. Если оглавление должно идти после титула, поставьте { rel: contents } в нужную позицию entry и снова проверьте последовательность страниц.
  4. Шаг 4. Измените объём первой главы на несколько абзацев и выполните полную пересборку. Номера следующих разделов должны измениться автоматически.
  5. Шаг 5. В готовом PDF откройте панель закладок и сравните её структуру с оглавлением. Это разные навигационные механизмы, поэтому каждый проверяется отдельно.

Для обложки поле cover может ссылаться на изображение или объект с дополнительными параметрами. Печатная обложка как страница и изображение обложки электронного пакета — не одно и то же; при нескольких форматах проверяйте оба сценария. Если обложка должна полностью заполнять лист, подготавливайте изображение в нужной пропорции и контролируйте вылет, а не растягивайте случайный растр. Общую процедуру создания документов также можно сопоставить с инструкцией по созданию PDF на Xeon Live.

Автоматизация, ускорение сборки и диагностика ошибок

Vivliostyle CLI хорошо ложится в автоматический выпуск именно потому, что все значимые параметры можно хранить в проекте. Надёжная схема фиксирует версию Node.js, зависимость @vivliostyle/cli, lock-файл, шрифты, конфигурацию и команду сборки. Тогда локальный компьютер и CI выполняют одну и ту же последовательность.

npm scripts, пакетная обработка и CI

npm scripts для Vivliostyle CLI
npm scripts превращают повторяемые команды build и preview в часть проекта.
  1. Шаг 1. В package.json добавьте сценарии "preview": "vivliostyle preview" и "build": "vivliostyle build". После этого рабочая команда использует npm run preview и npm run build без зависимости от глобальной установки.
  2. Шаг 2. Зафиксируйте lock-файл и не обновляйте зависимости перед каждым релизом автоматически. Обновление CLI или темы рассматривайте как изменение версточного окружения и сопровождайте визуальной проверкой.
  3. Шаг 3. Для серии однотипных документов экспортируйте массив конфигураций или формируйте его JavaScript-кодом. Каждый объект должен иметь собственный вход, название и путь результата. Перед запуском очистите каталог output.
  4. Шаг 4. В CI сначала устанавливайте зависимости из lock-файла, затем запускайте сборку, затем проверяйте существование ожидаемых файлов. Старый PDF не должен пережить неуспешный запуск и выглядеть как новый артефакт.
  5. Шаг 5. Кэшируйте зависимости и браузер только вместе с идентификатором платформы и lock-файла. После смены версии Node.js или образа контейнера чистая установка должна оставаться эталонным способом диагностики.
  6. Шаг 6. Для больших серий ограничивайте параллелизм. Несколько тяжёлых книг запускают отдельные браузерные процессы, поэтому контролируемая очередь часто стабильнее, чем одновременный старт всех заданий.

Ускорять редактирование лучше уменьшением области проверки, а не снижением качества финального PDF. Во время работы откройте одну главу или используйте --quick, но перед выпуском всегда соберите полный проект. Тяжёлые фотографии уменьшайте до разумного физического размера, сложные SVG очищайте от невидимых объектов, а сетевые шрифты и изображения заменяйте локальными фиксированными копиями, когда требуется повторяемость.

Типичные ошибки и порядок диагностики

  • Команда не запускается. Выполните node --version и npm --version, затем npx vivliostyle help. Если глобальная и проектная установки расходятся, используйте npx или npm script из текущего проекта и сравните версию CLI.
  • CSS или изображение не найдено. Проверьте рабочий каталог, относительный путь, регистр имени файла и сгенерированный HTML в workspaceDir. В контейнере ресурс обязан находиться внутри доступного дерева.
  • Viewer и PDF отличаются. Исключите --quick, убедитесь, что preview и build читают одну конфигурацию, затем сравните набор шрифтов и локальные ресурсы. Разные среды почти всегда дают разные переносы.
  • Номера в оглавлении пусты. Проверьте id заголовков, href ссылок и присутствие целевых глав в одной публикации. Затем выполните полную пагинацию без ускоренного режима.
  • Текст выходит за поле. Ищите длинный URL, код с запретом переноса, фиксированную ширину таблицы или white-space: nowrap. Исправляйте проблемный тип элемента, а не уменьшайте шрифт всей книги.
  • Сборка долго не завершается. Сократите проект до одной проблемной главы и делите содержимое пополам, пока не найдёте блок. Причиной часто становится чрезмерно большой неразрывный элемент, тяжёлый SVG, конфликтующие правила разрыва или зависший сетевой ресурс.

Почему после установки не находится команда vivliostyle?

Проектную установку запускают через npx vivliostyle или npm script. Для глобальной установки каталог исполняемых файлов npm должен быть доступен оболочке. Сначала сравните фактическую версию Node.js и путь запуска.

Почему --quick нельзя использовать для финальной проверки?

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

Почему после смены шрифта сдвинулось всё оглавление?

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

Почему локальная картинка работает, а в контейнере пропадает?

Контейнер видит только смонтированные каталоги. Переместите ресурс внутрь проекта или явно добавьте каталог в окружение сборки и исправьте относительный путь.

Можно ли править один абзац прямо в готовом PDF?

Рабочий процесс Vivliostyle CLI предполагает правку исходного Markdown, HTML или данных и последующую пересборку. Для точечной правки чужого PDF без исходников нужен PDF-редактор.

Что проверить, если итоговый PDF слишком большой?

Сначала оцените размер растров, встроенных шрифтов и сложных SVG. Уменьшайте конкретные тяжёлые ресурсы, а после внешней оптимизации заново проверяйте ссылки, закладки и читаемость.

Плюсы, минусы, альтернативы и практический выбор

Vivliostyle CLI наиболее логичен там, где документ уже существует как код и контент: Markdown, HTML, CSS, шаблоны и данные. В таком контексте его главное преимущество — не отдельная функция экспорта, а воспроизводимый конвейер. Версию публикации можно связать с commit, изменения верстки видны в diff, а выпуск повторяется локально и на сервере.

Разворот Vivliostyle Viewer со сложным содержимым
Сложный разворот показывает, что один документ может сочетать текст, ссылки, формулы и другие веб-элементы.

Плюсы

  • Текстовые исходники и CSS удобно хранить в системе контроля версий и рецензировать построчно.
  • Один проект может выпускать PDF и, для подходящих входов, электронные форматы.
  • Параметры страницы, оглавление и колонтитулы автоматизируются вместо ручной правки каждой страницы.
  • Vivliostyle Viewer показывает фактическую пагинацию до финального экспорта.
  • Есть темы, VFM, JavaScript API и интеграция с современными фронтенд-процессами.
  • Командный интерфейс естественно встраивается в CI и пакетную генерацию документов.

Минусы

  • Нет визуального редактора, где макет собирается перетаскиванием блоков мышью.
  • Для уверенной настройки печатной верстки нужны HTML и CSS Paged Media.
  • Шрифты, сетевые ресурсы и версия браузерного движка влияют на пагинацию, поэтому среду надо контролировать.
  • Сложные таблицы, крупные неразрывные блоки и нестандартная веб-разметка требуют отдельных тестов на границах страниц.
  • Программа не предназначена для OCR и ручной правки уже готового чужого PDF.

Кому подойдёт

  • Техническим писателям и командам документации, которые ведут материалы в Markdown или HTML.
  • Разработчикам, создающим отчёты и документы из шаблонов и данных.
  • Издательским командам, которым подходит верстка через CSS и нужен воспроизводимый выпуск.
  • Авторам книг и методичек, работающим с текстовыми исходниками и Git.

Кому лучше выбрать другой инструмент

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

Из близких по идее решений Prince преобразует HTML/XML и CSS в PDF и ориентирован на зрелый печатный конвейер; WeasyPrint удобен в Python-проектах, где HTML/CSS генерируются серверно; Paged.js CLI строит paged media поверх браузерного стека; Antenna House Formatter работает с HTML/CSS и XSL-FO и рассчитан на крупные издательские и документационные процессы. Выбор между ними зависит не от одной функции, а от стека проекта, требований к стандартам, поддержки, формату исходников и степени автоматизации.

Для Vivliostyle CLI рациональная стратегия проста. Если материал живёт в Markdown или HTML и будет обновляться много раз, сначала соберите минимальный PDF, затем перенесите параметры в config, подключите тему и CSS, после этого добавьте оглавление, обложку и автоматизацию. Если задача разовая и состоит в редактировании уже существующего PDF, не стоит восстанавливать весь проект ради одной правки. А когда готовый файл получился слишком тяжёлым, полезно отдельно изучить способы уменьшить размер PDF и после оптимизации повторно проверить документ.

В результате Vivliostyle CLI лучше всего раскрывается не как разовый конвертер, а как часть управляемой публикационной системы. Стабильный проект хранит рукопись, ресурсы, стили, конфигурацию и зависимости рядом; preview используется для контрольной пагинации, build — для выпуска, а автоматизация повторяет тот же сценарий на сервере. Такой подход требует дисциплины, зато после настройки позволяет выпускать длинные материалы без ручного обслуживания каждой страницы.

xeonlive.ru
Профиль автора на Sostav