Конвертер MD → PDF-книга

Для постраничной книжной вёрстки используется открытый проект Vivliostyle CLI. Исходником остаётся обычный Markdown рядом с папкой изображений; правила полос хранятся в Git в scripts/book-print.css, а точная версия конвертера — в pnpm-lock.yaml.

Уровень автоматизации

Команда book:pdf полностью автоматизирует сборку одной указанной книги:

• читает MD и YAML-frontmatter;
• добавляет обложку и применяет A4-вёрстку;
• размещает отдельные иллюстрации на правых полосах;
• сохраняет ссылки и сноски;
• создаёт PDF во временном каталоге, оптимизирует его через Ghostscript и записывает готовый файл рядом с MD;
• не пересобирает актуальный PDF без флага --force.

Запуск команды пока ручной. Скрипт не следит за каталогом, не запускается при git commit или git push, не создаёт commit и не публикует сайт. Git CI для автоматического запуска пока не настроен.

Быстрый запуск

Из корня проекта:

corepack pnpm install --frozen-lockfile
corepack pnpm book:pdf -- "books/раздел/книга/книга.md"

Это штатная команда и для первой, и для всех следующих MD-книг. Скрипт принимает один исходный MD за запуск. Если нужно собрать несколько книг, команду вызывают для каждой из них отдельно.

Без пути команда собирает «ДОТУ 2». PDF создаётся рядом с MD с суффиксом [книжное издание]. Повторный запуск пропускает актуальный PDF; --force пересобирает его принудительно:

corepack pnpm book:pdf -- "books/раздел/книга/книга.md" --force

Другой путь результата:

corepack pnpm book:pdf -- "books/раздел/книга/книга.md" \
  --output "books/раздел/книга/издание.pdf"

Правила макета

• формат A4 и зеркальные внутренние поля;
• первая полоса автоматически собирается как сквозная типографская обложка: заголовок, подзаголовок и издательская подпись берутся из YAML-frontmatter;
• части (#) и главы (##) начинаются с новой страницы без добавления пустой полосы ради чётности;
• отдельные Markdown-иллюстрации всегда начинаются с правой полосы, а теория после них продолжается с левой; при необходимости автоматически добавляется пустая полоса;
• ссылки и сноски остаются активными в PDF;
• пустые страницы между смысловыми блоками допустимы и не нумеруются визуально.

Чтобы картинка считалась отдельной книжной иллюстрацией, размещайте её отдельным абзацем:

![Подпись к схеме](img/schema.png)

Опциональные метаданные обложки:

---
title: "Название"
subtitle: "Подзаголовок"
cover_title: "Заголовок на обложке"
cover_subtitle: "Подзаголовок на обложке"
cover_imprint: "Частное издание 2026"
---

Работа через Git

В Git достаточно хранить MD, изображения, scripts/book-print.css, scripts/md-book-to-pdf.mjs, package.json и pnpm-lock.yaml. Полученный PDF можно хранить рядом с исходником, если он должен попасть в библиотеку сайта, или публиковать как артефакт CI. Конвертация не требует Pandoc/LaTeX и использует установленный Chrome/Chromium; при нестандартном пути задайте BOOK_PDF_BROWSER=/путь/к/chrome.

Для локальной сборки необходимы:

• Node.js и зависимости проекта из pnpm-lock.yaml;
• Chrome или Chromium;
• Ghostscript по пути /usr/bin/gs.

Что можно автоматизировать в CI

Git CI может запускать тот же скрипт без изменения формата исходников. Типовой конвейер должен:

1. получить репозиторий и выполнить corepack pnpm install --frozen-lockfile;
2. установить или предоставить Chrome/Chromium и Ghostscript;
3. определить изменённые MD-книги и для каждой вызвать pnpm book:pdf;
4. выполнить corepack pnpm check;
5. сохранить PDF как CI-артефакт либо включить его в production-сборку сайта.

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

Проверка результата

После конвертации можно проверить формат и число страниц:

pdfinfo "books/раздел/книга/книга [книжное издание].pdf" \
  | grep -E '^(Pages|Page size|File size)'

Для попадания новой книги в каталог затем выполняется общая проверка и сборка:

corepack pnpm check