Формирование документации в PDF

Назначение и требования

PDF формируется локально из тех же версионированных страниц, которые доступны на сайте. Для работы нужны Node.js версии 22.12 или новее, установленные зависимости проекта и браузер Chrome либо Chromium. Команды выполняют из каталога team-docs.

Перед первым запуском подготовьте окружение:

nvm use
pnpm install
pnpm artifacts:check
pnpm docs:check

Отдельный файл для каждой страницы

Автономный режим собирает сайт, временно запускает его на порту 3110, формирует PDF для всех страниц и завершает сервер:

pnpm pdf:build

Результаты повторяют структуру документации в dist/pdf. Например, эта инструкция будет сохранена в dist/pdf/2026.3.3/developer/pdf-generation.pdf. Состав и размер файлов записываются в dist/pdf/pdf-manifest.json.

Если сайт уже запущен командой pnpm dev на порту 3100, повторная сборка не нужна:

pnpm pdf:export

Для экспорта одной страницы передайте ее маршрут. Несколько маршрутов можно перечислить в том же значении через запятую:

TEAM_DOCS_PDF_PATHS=/docs/2026.3.3/developer/pdf-generation pnpm pdf:export

Примечание: Неизвестный маршрут завершает команду ошибкой до начала печати.

Установка переменной окружения для PowerShell:

$env:TEAM_DOCS_PDF_PATHS="/docs/2026.3.3/developer/pdf-generation"

При экспорте в Windows может понадобиться явно указать путь к браузеру Chrome:

$env:TEAM_DOCS_PDF_BROWSER_PATH="C:\Program Files (x86)\Google\Chrome\Application\chrome.exe"

Единый комплект по текстовой карте

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

pnpm pdf:bundle:build

При уже работающем локальном сайте используйте сокращенный режим:

pnpm pdf:bundle

Стандартная карта находится в pdf/agent-platform-2026.3.3.txt. Директива @title задает заголовок комплекта, @output — относительный путь результата, строки с # — группы оглавления, а маршруты определяют порядок документов:

@title Комплект документации
@output 2026.3.3/agent-platform-docs.pdf

# Руководства администратора
/docs/2026.3.3/admin/deployment
/docs/2026.3.3/admin/platform_components

Другую карту передайте явно:

TEAM_DOCS_PDF_MAP=pdf/my-release.txt pnpm pdf:bundle

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

Настройка запуска

Пример с нестандартным браузером и отдельным каталогом:

TEAM_DOCS_PDF_BROWSER_PATH=/usr/bin/chromium \
TEAM_DOCS_PDF_OUTPUT_DIR=/tmp/agent-platform-pdf \
  pnpm pdf:bundle:build

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

После изменения карты или печатных стилей выполните полный контроль:

pnpm pdf:test
pnpm pdf:bundle:build
pnpm check

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