Обзор Vivliostyle CLI: CSS-вёрстка публикаций и сборка PDF из командной строки

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

Скачать Vivliostyle CLI

Безопасный путь получения Vivliostyle CLI — официальный пакет @vivliostyle/cli из npm либо официальный контейнер проекта из GitHub Container Registry. На дату проверки npm помечает 11.2.0 как текущий тег latest. Отдельного установщика EXE, DMG или традиционного Linux-пакета в основной схеме распространения нет: продукт устанавливается как Node.js-пакет. Это важно для идентификации — Vivliostyle CLI нельзя смешивать с веб-приложением Vivliostyle Viewer, браузерным Vivliostyle Pub или библиотекой Vivliostyle Core.

Для системной установки документация предлагает команду npm install -g @vivliostyle/cli. Если зависимость нужна только конкретному проекту, используется npm install @vivliostyle/cli. Для нового книжного проекта актуальная документация рекомендует генератор npm create book@latest, который создаёт структуру проекта и конфигурацию. Такой способ удобнее ручного старта, когда нужны шаблон, тема и готовые сценарии build/preview.

Что такое Vivliostyle CLI

Vivliostyle CLI — часть открытой экосистемы Vivliostyle, развиваемой сообществом проекта и Vivliostyle Foundation. Назначение продукта — взять веб-документ, применить к нему механизмы CSS-пагинации Vivliostyle и получить публикационный результат. В терминологии проекта Viewer отвечает за отображение и вёрстку HTML+CSS в браузере, Core является движком, а CLI оркестрирует подготовку входных данных, запуск локального сервера и браузера, пагинацию, предпросмотр и финальный экспорт.

Это не WYSIWYG-приложение. Основная единица работы — проект с исходными файлами и конфигурацией vivliostyle.config.js или vivliostyle.config.json. В конфигурации задаются входы, порядок глав, метаданные, тема, размер страницы, выходные файлы, директория промежуточных данных и дополнительные параметры. Один и тот же набор исходников можно собирать повторно на локальной машине, в скриптах или на сервере.

Текущий статус активный. Документация Vivliostyle была обновлена 24 августа 2026 года под Vivliostyle CLI 11.2.0, Vivliostyle.js 2.45.0 и VFM 2.7.2. Ветка 11.x продолжает получать изменения движка и инфраструктуры, а версия 11.2.0 добавила настройку toc.compose для композиции содержимого навигационного оглавления. Это не продукт, снятый с поддержки, и не историческая ветка.

Основные функции Vivliostyle CLI

Сборка PDF из HTML и Markdown

Базовая операция — vivliostyle build. В качестве входа можно передать локальный HTML или Markdown, а через параметр вывода указать PDF. Markdown предварительно преобразуется с помощью VFM, Vivliostyle Flavored Markdown, после чего движок применяет HTML/CSS-вёрстку и разбивает материал на страницы. Если исходник уже подготовлен как HTML, можно сохранить существующую семантику и стили, а дополнительные правила подключить через CSS.

CLI умеет работать не только с одиночным файлом. Конфигурация допускает массив entry, где главы перечисляются в нужном порядке и каждой можно назначить заголовок или собственную тему. Это превращает сборку книги в описываемый проектом процесс вместо ручного объединения готовых PDF. Для многоглавных документов доступны служебные сущности обложки и оглавления, а также управление началом главы с левой, правой, recto- или verso-страницы.

CSS для печатной страницы

Сильная сторона Vivliostyle — использование CSS Paged Media и связанных модулей. Поддерживаются правила размера страницы, поля, маркеры обреза, bleed, именованные страницы, running content и другие средства, актуальный перечень которых ведётся в справочнике движка. На уровне CLI размер можно задать готовыми пресетами A5, A4, A3, B5, B4, JIS-B5, JIS-B4, letter, legal, ledger или собственными размерами. Параметры crop marks, bleed и crop offset позволяют готовить макет ближе к требованиям печати, а не просто печатать веб-страницу через браузер.

Стили подключаются несколькими способами: обычным CSS из HTML, дополнительным author stylesheet, user stylesheet, строкой CSS или Vivliostyle Theme. Официальные темы распространяются как npm-пакеты; локальная тема может быть отдельным CSS-файлом или npm-совместимым пакетом. Если указанная npm-тема ещё не установлена, CLI способен установить её в проектное окружение, поэтому для полностью автономной сборки зависимости лучше зафиксировать заранее.

Предпросмотр и быстрый режим

Команда vivliostyle preview запускает локальный сервер и открывает Vivliostyle Viewer в браузере. Это основная визуальная рабочая зона продукта: терминал сообщает состояние процесса, а Viewer показывает разбитый на страницы документ. Такой режим позволяет отлаживать CSS, разрывы страниц, колонтитулы, оглавление и оформление до выпуска файла.

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

EPUB, WebPub и публикационные манифесты

Помимо PDF команда build выводит EPUB 3 и WebPub. EPUB создаётся как пакет EPUB 3, однако применяемые CSS-файлы попадают туда как есть; совместимость внешних EPUB-читалок поэтому зависит от того, насколько выбранные стили соответствуют возможностям этих читалок. WebPub создаётся как каталог с publication.json и ресурсами, что удобно для веб-публикации и последующей повторной сборки.

Оглавление, закладки и обложка

Проектная конфигурация умеет создавать HTML-страницу оглавления и управлять её положением. Наличие корректного TOC имеет дополнительный эффект: при PDF-выводе CLI формирует закладки на основе оглавления. Для входного EPUB используются данные оглавления EPUB. В 11.2.0 появился toc.compose, расширяющий управление тем, как строится содержимое навигационного элемента TOC.

Печатный PDF/X-1a и постобработка

Для типографского сценария предусмотрен preflight в режим press-ready, который формирует PDF/X-1a. Официальная инструкция требует Docker для рекомендуемого варианта post-processing; есть и press-ready-local, но документация в общем случае рекомендует Docker-окружение. В современной конфигурации параметры preflight собраны в pdfPostprocess; старые отдельные поля помечены как устаревающие. Там же доступны настройки работы с device-cmyk и замены изображений при постобработке.

PDF/X-1a здесь не заменяет полный prepress-контроль: требования типографии к цвету, шрифтам, прозрачностям и overprint нужно проверять отдельно. Для инспекции или ручной коррекции уже полученного PDF может понадобиться специализированный редактор, например Adobe Acrobat Pro.

Интеграция с Vite и JavaScript API

Пакет также экспортирует JavaScript API: build, preview, create, createVitePlugin, defineConfig и VFM. Поэтому Vivliostyle CLI можно вызывать не только как отдельную команду оболочки, но и из Node.js-кода. При серверной интеграции важно учитывать AGPL: официальный FAQ отдельно разрешает вызывать CLI из проприетарной серверной программы как независимый процесс; более тесное включение кода требует отдельной лицензионной оценки.

Интерфейс и удобство использования

У Vivliostyle CLI две фактические рабочие зоны. Первая — терминал, где выполняются create, init, build и preview и выводятся предупреждения, прогресс и ошибки. Вторая — окно браузера с Vivliostyle Viewer для визуального контроля. Отдельного проекта с панелями, лентой инструментов и диалогами «Сохранить как PDF» нет. Пользователь редактирует Markdown, HTML, CSS и конфигурацию в выбранном текстовом редакторе или IDE, а CLI выполняет сборку.

Порог входа зависит от задачи. Чтобы превратить простой Markdown в PDF, достаточно нескольких команд и готовой темы. Для точной книжной вёрстки нужны знания CSS, правил @page, структуры HTML, особенностей шрифтов и поведения браузерного движка. Поэтому продукт удобен разработчикам документации и техническим редакторам, но будет непривычен пользователю, ожидающему визуальное перетаскивание блоков.

Команды и параметры CLI англоязычные. Официальная документация поддерживается на английском и японском; отдельного русского интерфейса как такового нет. Это не ограничивает язык самого издания: Unicode-текст, язык документа и направление чтения задаются данными и конфигурацией, а фактический результат дополнительно зависит от наличия нужных шрифтов.

Удобнее держать исходники, CSS, шрифты, изображения, конфигурацию и package.json в одном проекте. Тогда preview образует короткий цикл редактирования, а build — повторяемую финальную операцию. В отличие от LibreOffice Writer, макет меняют не в визуальном редакторе, а в текстовых файлах, что удобно для Git и code review.

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

HTML и CSS являются центральным форматом экосистемы. CLI может собрать локальную страницу, внешнюю HTTPS/HTTP-страницу или многофайловую WebBook-структуру. Для сайтов, предварительно собранных фронтенд-фреймворком, параметр static монтирует каталог в локальный сервер, чтобы связанные изображения и ресурсы корректно разрешались. В конфигурации также предусмотрены правила копирования assets при экспорте.

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

Финальный PDF можно открыть в любом современном просмотрщике. Если задача после сборки — только быстро читать, искать и печатать документ в Windows, Sumatra PDF проще и легче по роли: это готовый reader, а не конвейер генерации. Для дополнительной проверки результата можно использовать, например, Foxit Reader или другой независимый просмотрщик, чтобы убедиться, что закладки, страницы и шрифты ведут себя ожидаемо вне Vivliostyle Viewer.

Производительность и стабильность

Vivliostyle CLI выполняет настоящую браузерную пагинацию, поэтому ресурсоёмкость определяется не только размером текста. На время влияют число страниц, сложность CSS, изображения, web fonts, математическая разметка, внешние ресурсы и количество документов в публикации. Универсальных официальных цифр «страниц в секунду» проект не обещает, поэтому сравнивать производительность корректнее на собственном репрезентативном макете.

Для долгих сборок важны timeout и прогресс. По умолчанию CLI отводит build 300 секунд, значение можно изменить. С версии 11.1 терминал показывает ход пагинации — текущий документ, число страниц и процент, поэтому длительную работу проще отличить от зависания.

Режим —quick полезен для длинных документов, но не подходит для финальной сверки нумерации и переносов: он намеренно оценивает число страниц приблизительно. Сборки с внешними URL, CDN и web fonts зависят от сети, поэтому критичные assets и версии пакетов лучше фиксировать локально.

Docker помогает стандартизовать окружение, но полный renderMode: docker с версии 11.0.3 deprecated и может быть удалён. При этом Docker остаётся рекомендуемым для press-ready post-processing. Новый долгоживущий процесс лучше не привязывать к устаревающему renderMode.

Лицензирование и версии

Vivliostyle CLI распространяется по GNU Affero General Public License v3. Платной редакции CLI, подписки, ограничения числа страниц, пробного срока и обязательной регистрации в официальной модели нет. Пакет можно устанавливать и использовать бесплатно, в том числе внутри компании. Официальный FAQ подчёркивает, что AGPL не переносится автоматически на созданные публикации: готовый PDF, EPUB или исходные HTML/CSS не обязаны становиться открытыми только потому, что для их сборки использован Vivliostyle.

Лицензионные обязательства появляются при изменении, распространении или сетевом предоставлении самого AGPL-компонента и при тесном включении его в единый производный продукт. Проект отдельно указывает, что серверная программа может вызывать Vivliostyle CLI как независимый процесс и оставаться проприетарной. Для коммерческой SaaS-интеграции с модифицированным CLI всё равно стоит рассматривать конкретную архитектуру вместе с текстом лицензии, а не заменять юридическую проверку кратким FAQ.

Системные требования

Node.js и пакетный менеджер

Актуальная документация требует Node.js 22.12.0 или новее; ветка 11.0.1 прекратила поддержку Node.js 20. Официальные команды используют npm. Документация допускает другие runtime, например Bun или Deno, но основной путь установки и примеры построены вокруг Node.js.

Браузерный движок

Начиная с CLI 10 браузерная библиотека переведена с Playwright на Puppeteer. Конфигурация позволяет выбирать браузер или задавать путь к исполняемому файлу; WebKit после миграции не поддерживается. Браузер нужен Viewer и процессу PDF-пагинации.

Windows, macOS и Linux

Vivliostyle CLI распространяется как Node.js-пакет, а не как нативное GUI-приложение. История релизов содержит исправления для Windows 11 и WSL, для Linux есть официальный контейнер; на macOS применяется npm-схема при совместимых Node.js и браузере. Отдельных официальных минимальных версий настольных ОС в Getting Started не указано.

Дополнительные требования для печати и Docker

Для рекомендуемого PDF/X-1a press-ready требуется Docker. Официальный контейнер включает компоненты постобработки, включая Ghostscript и poppler-utils. Собственные шрифты должны быть доступны именно тому окружению, где выполняется финальная сборка.

Преимущества и недостатки Vivliostyle CLI

Плюсы и минусы

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

Сильная поддержка paged CSS. Размеры страниц, running content, bleed, crop marks, двусторонняя логика и другие книжные конструкции являются частью основной модели, а не обходным путём через «Печать».

Несколько форматов результата. Один проект способен формировать PDF, EPUB 3 и WebPub; выходы можно перечислять в конфигурации.

Предпросмотр на том же движке. Команда preview открывает Vivliostyle Viewer, поэтому визуальная отладка связана с тем же типографским стеком, что и build.

Открытая лицензия без платы за выпуск. Нет подписки, лимита страниц и водяных знаков; готовые публикации не наследуют AGPL автоматически.

Интеграция с веб-стеком. Vite, статически собранные сайты, темы npm и JavaScript API позволяют встроить генерацию документов в CI/CD.

Минусы

Нет визуального редактора макета. Для серьёзной настройки необходимо понимать HTML/CSS и читать сообщения терминала.

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

Выходной EPUB требует отдельной проверки. CSS переносится в EPUB, но поддержка конкретных свойств зависит уже от сторонней читалки.

Входной EPUB ограничен PDF-выводом. По официальной матрице это не средство «перепаковать EPUB в EPUB».

Печатная цепочка не заменяет prepress-контроль. PDF/X-1a и CMYK-related функции полезны, но требования типографии и итоговый PDF необходимо валидировать отдельно.

Эволюция Node.js и браузерной части может ломать окружение. За последние major-релизы минимальная версия Node.js повышалась несколько раз, поэтому старые CI-образы требуют обслуживания.

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

Sumatra PDF не прямой конкурент: он читает готовые документы, а Vivliostyle CLI их собирает. Практичная связка — выпуск PDF через Vivliostyle и независимая проверка/чтение результата в Sumatra PDF. Для ручной правки существующего PDF нужен редактор, например PDF-XChange Editor.

Инструкция по установке

Установка через npm

1. Установите Node.js версии 22.12.0 или новее и убедитесь, что команды node -v и npm -v доступны в терминале.

2. Для глобальной установки выполните npm install -g @vivliostyle/cli. Если зависимость должна принадлежать только одному проекту, выполните npm install @vivliostyle/cli в каталоге проекта.

3. Проверьте установку командой vivliostyle —version. Для просмотра списка действий используйте vivliostyle help.

4. Подготовьте минимальный HTML или Markdown и выполните, например, vivliostyle build manuscript.md -s A4 -o manuscript.pdf. Результат должен появиться по указанному пути.

5. Для визуальной проверки запустите vivliostyle preview manuscript.md. CLI откроет Viewer в браузере; закройте preview после контроля.

Создание нового проекта

1. В пустом рабочем каталоге выполните npm create book@latest.

2. Ответьте на вопросы генератора о названии, авторе, языке и шаблоне. Встроенные варианты включают Minimal, Basic, Documentation, Novel, Academic и Magazine.

3. Проверьте созданный vivliostyle.config.js, прежде чем добавлять собственные документы. Особое внимание уделите entry, theme, output и размеру страницы.

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

Безопасное удаление

Глобальную установку удаляют командой npm uninstall -g @vivliostyle/cli, локальную — npm uninstall @vivliostyle/cli в каталоге проекта. До удаления сохраните исходники, CSS, шрифты, конфигурацию, lock-файл и нужные PDF/EPUB/WebPub. Рабочий workspaceDir можно очищать только после проверки, что в нём нет единственной копии полезных ресурсов.

Практические кейсы

Техническая книга из нескольких Markdown-глав

Цель. Собрать одну PDF-книгу из Markdown-глав. Подготовка. Перечислите главы в entry и выберите тему. Шаги. Запустите preview, настройте toc, затем выполните build. Проверка. Сверьте начало глав, нумерацию и PDF-закладки. Ограничение. —quick не годится для окончательной проверки номеров страниц.

Один контент для сайта и печатной версии

Цель. Получить PDF из статической сборки сайта. Подготовка. Соберите конечные HTML и assets, например в dist. Шаги. Укажите каталог в static, а entry — абсолютными путями, подключите печатный CSS. Проверка. Сравните заголовки, изображения и ссылки в Viewer и PDF. Ограничение. Viewer не предназначен для SPA-маршрутизации и динамического изменения HTML на клиенте.

PDF с метками обреза и вылетами

Цель. Сделать макет с bleed и crop marks. Подготовка. Получите от типографии trim size и величину вылетов. Шаги. Задайте размер страницы, bleed, метки и при необходимости crop offset; для PDF/X-1a примените press-ready. Проверка. Сверьте физический размер и требования типографии. Ограничение. Успешный PDF/X-1a build не гарантирует соответствия всем внутренним нормам производства.

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

Цель. Получить PDF из EPUB. Подготовка. Убедитесь, что содержимое EPUB доступно и нужные шрифты установлены. Шаги. Передайте EPUB команде build с PDF-выходом. Проверка. Сверьте оглавление, порядок глав, иллюстрации и специальные символы. Ограничение. Входной EPUB не заявлен как источник нового EPUB/WebPub.

Автоматическая сборка в CI

Цель. Выпускать PDF в CI. Подготовка. Зафиксируйте версию CLI, lock-файл, шрифты и assets. Шаги. В CI установите Node.js 22.12+ и зависимости, затем вызовите build с фиксированной конфигурацией. Проверка. Сохраните PDF как артефакт и контролируйте успешность сборки и ожидаемый порядок страниц. Ограничение. Внешние web fonts и незакреплённые темы снижают воспроизводимость.

Контроль перед сохранением и передачей

Выполнить финальный build без —quick и убедиться, что процесс завершился без ошибок.

Проверить размер страницы, поля, bleed и crop marks в соответствии с назначением файла.

Открыть PDF вне Vivliostyle Viewer и проверить закладки, ссылки, поиск текста и несколько страниц с разной структурой.

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

Убедиться, что шрифты и специальные символы не заменились на fallback; особенно это важно при переходе с локальной машины на CI или Docker.

Если передаётся EPUB, проверить его минимум в двух независимых EPUB-читалках, потому что CSS-возможности отличаются.

Если заявляется PDF/X-1a, выполнить профильную проверку файла и сверить требования типографии, а не полагаться только на успешный build.

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

Карта критических зависимостей

Локальный preview server по умолчанию использует порт 13000; адрес прослушивания настраивается. Для обычного просмотра его не нужно открывать в сеть. Если host разрешён для внешних адресов, доступ к проектным ресурсам следует считать сетевым и ограничивать контролируемой средой.

vivliostyle.config.js — исполняемый JavaScript, поэтому чужой проект нужно проверять как код: package.json, lock-файл, конфигурацию и install-скрипты зависимостей. Для декларативной конфигурации без программной логики поддерживается JSONC-файл vivliostyle.config.json.

Паспорт обратимости операций

Обратимость высока, пока источником истины остаются Markdown/HTML/CSS, а PDF считается производным файлом. Исправления лучше вносить в исходник и пересобирать: ручная правка PDF будет потеряна при следующем build. Для WebPub сохраняйте publication.json и assets, для EPUB — исходный проект; экспортный файл не стоит превращать в единственную редактируемую копию.

Хронология развития и поддержки

История релизов показывает быстро меняющиеся зависимости от Node.js и браузеров. Для конкретного выпуска разумно закреплять рабочую версию CLI, а переход на новую ветку проводить отдельной задачей с повторной визуальной проверкой ключевых страниц.

Часто задаваемые вопросы

Нужен ли аккаунт Vivliostyle?

Нет. Для установки @vivliostyle/cli и локальной сборки регистрация в сервисе Vivliostyle не требуется. npm-зависимости и удалённые ресурсы требуют сети только тогда, когда их действительно нужно загрузить.

Отправляет ли Vivliostyle CLI мои документы в облако?

Обычный локальный build работает как локальный Node.js/браузерный процесс и не требует загрузки рукописи в облачный сервис Vivliostyle. Однако документ может сам ссылаться на внешние изображения, шрифты, CSS или URL, а отсутствующая npm-тема может скачиваться. Для конфиденциального материала используйте локальные assets и контролируемый сетевой режим.

Можно ли использовать Vivliostyle CLI коммерчески?

Да. AGPL v3 разрешает коммерческое использование. Готовые публикации не обязаны становиться AGPL. Ограничения касаются прежде всего распространения/модификации самого Vivliostyle и тесного программного включения его кода; серверный вызов CLI как независимого процесса официальный FAQ рассматривает как допустимую модель.

Можно ли редактировать готовый PDF в Vivliostyle CLI?

Нет в смысле привычного PDF-редактора. Рабочая модель обратная: изменяются исходные Markdown/HTML/CSS, затем PDF пересобирается. Если задача — исправить текст или объект только в существующем PDF без исходников, нужен специализированный редактор.

Подходит ли Vivliostyle CLI для DOCX?

Прямой DOCX-вход в официальной матрице не заявлен. Практический путь — сначала преобразовать DOCX в контролируемый HTML или Markdown, затем доработать структуру и CSS. Для документов, которые должны оставаться редактируемыми в офисном формате, удобнее использовать офисный пакет, а Vivliostyle подключать уже на этапе публикационного экспорта.

Нужен ли Docker?

Для обычного локального PDF, EPUB или WebPub — не обязательно. Docker требуется для рекомендуемого press-ready PDF/X-1a post-processing. Полный renderMode docker сейчас deprecated, поэтому его не стоит путать с необходимостью Docker именно для печатного preflight.

Можно ли запускать CLI на сервере?

Да. Пакет имеет JavaScript API и обычный командный интерфейс, а официальный лицензионный FAQ отдельно описывает серверный вызов. Для стабильной эксплуатации фиксируйте версию Node.js, CLI, браузера, шрифтов и зависимостей и не делайте production-сборку зависимой от случайных внешних URL.

Вывод

Vivliostyle CLI подходит командам, которые хранят рукопись в Markdown/HTML, управляют печатным дизайном через CSS, используют Git и хотят собирать PDF вместе с EPUB/WebPub. Особенно логичен он для технической документации, книг и отчётов рядом с JavaScript/Vite-стеком.

Он хуже подходит пользователям, которым нужен визуальный редактор страниц или непосредственная правка существующего PDF. В этих сценариях разумнее WYSIWYG-редактор или PDF-редактор. Sumatra PDF остаётся инструментом другой стороны процесса — чтением готовых документов на Windows, а Vivliostyle CLI отвечает за генерацию.