Книга из нескольких Markdown-файлов: экспорт в PDF и ZIP-архив

Один файл README — отличная визитная карточка проекта, но плохая основа для полноценной документации. Когда проект обрастает главами по установке, настройке, эксплуатации и решению проблем, бесконечный README становится неудобным для чтения и не поддается аккуратной ручной верстке.

В md2pdf встроен режим работы с книгами документации. Укажите публичный репозиторий, выберите нужные Markdown-файлы, упорядочьте главы, добавьте обложку и оглавление. Затем распечатайте книгу целиком или скачайте ZIP-архив с отдельными PDF для каждой главы. Все операции выполняются в браузере без выгрузки данных на сервер.

В этом руководстве объясняются правила подготовки репозитория. Если вам нужен экспорт только одного файла, ознакомьтесь с материалом Как преобразовать README с GitHub в PDF.

Когда книга лучше одиночного README

Используйте режим книги, когда документация делится на смысловые разделы и читателю важно ориентироваться в структуре:

• Документация к продукту с отдельными страницами по установке, архитектуре и справочникам.
• Учебные материалы, собранные из модулей или лекций.
• Регламенты и инструкции (runbooks), где каждый сценарий живет в отдельном файле.
• Пакет выпуска, объединяющий список изменений, инструкцию по обновлению и миграции.

Книга избыточна, если документ короток или изменяется каждые пять минут.

Режим работает с публичными репозиториями. Приватные репозитории не поддерживаются без серверной авторизации.

Что делает сканер репозитория

Получив адрес репозитория, сканер обращается к Git Trees API на GitHub и строит дерево файлов с удобными чекбоксами.

Для стабильной работы в браузере установлены четкие ограничения:

• До 30 файлов в книге.
• До 750 КБ на файл.
• Не более 6 МБ суммарного Markdown.
• Таймаут загрузки файлов 20 секунд.
• Бюджет в 60 запросов к GitHub API.

docs/
├── 00-introduction.md
├── 01-installation.md
├── 02-configuration.md
├── 03-operations.md
└── 04-troubleshooting.md

Рекомендуемая структура каталогов:

Числовые префиксы облегчают сортировку и делают порядок чтения наглядным в исходном коде.

Выбор и упорядочивание глав

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

Практические советы:

1. Ограничивайте объем. Хотя лимит равен 30 главам, книга из 10–15 глав читается и верстается гораздо лучше.
2. Введение в начале. Обзорные сведения должны идти перед установкой.
3. Справочники в конце. Глоссарии и таблицы API удобнее размещать в конце.
4. Не дублируйте README. Если README включен как глава, решите, является ли он введением или кратким резюме.
5. Исключайте служебные файлы. Убирайте автогенерируемые логи.

Порядок в списке строго соответствует порядку в итоговом документе и в архиве ZIP.

Подготовка исходных файлов

Рендерер считает каждый выбранный файл отдельной главой и автоматически проставляет заголовок главы.

Пример начала главы:

# Installation

This chapter assumes a supported Node.js version and a local clone.

Если каждый файл начинается с H1, книга получит естественные и четкие границы разделов.

На что обратить внимание:

• Относительные ссылки. Ссылки между главами должны указывать на файлы, вошедшие в книгу.
• Изображения. Относительные пути картинок разрешаются через репозиторий GitHub.
• Широкие таблицы. См. Таблицы Markdown в PDF для настройки ширины.
• Одинаковые заголовки. Добавляйте названия глав к повторяющимся подзаголовкам.

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

В редакторе можно задать название книги, подзаголовок и аннотацию. Это сразу дает читателю понять назначение и версию документа.

Оглавление формируется автоматически из выбранных глав и заголовков. Любые изменения требуют повторной сборки для исключения рассинхронизации.

Печать книги и экспорт в ZIP

Предусмотрено два варианта экспорта:

• Печать книги целиком. Отправляет сверстанную книгу (обложку, оглавление и главы) в диалог печати браузера.
• Скачивание в ZIP. Генерирует отдельный PDF на каждую главу и упаковывает их в ZIP-архив с сохранением путей.

Архив именуется как md2pdf-{owner}-{repo}-{sha8}.zip, имена файлов нормализованы по стандарту Unicode NFC.

Лимиты, ошибки и восстановление

Если превышен лимит API GitHub, подождите сброса счетчика или укажите путь к конкретной папке. Недоступные изображения заменяются плейсхолдерами без срыва экспорта.

Сравнение стилей описано в статье Сравнение тем оформления md2pdf.