Создание PDF из документации

Diplodoc может генерировать документацию в формате PDF.

Структура PDF-документа

PDF-документ состоит из трех частей:

1. Титульные страницы

   Отображаются в начале документации и не нумеруются.

   Титульные страницы указываются в блоке startPages в toc.yaml:

   pdf:
     startPages:
       - path-to-page-1.md
       - path-to-page-2.md
       - path-to-page-n.md
   

   Важно

   Страницы из pdf.startPages не поддерживают локализацию через yfm translate.

   При сборке документации титульные страницы не трансформируются в файлы. Для проверки их верстки в браузере, используйте при сборке флаг --pdf-debug: он создаст HTML-версии страниц из startPages.

2. Оглавление

   Diplodoc автоматически формирует оглавление на основе toc.yaml. Каждый пункт в списке — это ссылка на страницу.

   Названия разделов, объединяющих группу статей, отображаются простым текстом.
   Файлы с атрибутом hidden: true в toc.yaml не попадают в PDF. Чтобы включить их, установите параметр hiddenPolicy: false.

3. Основной контент

   В PDF поддерживаются все возможности Diplodoc:

   • блоки Page Constructor;
   • перекрестные ссылки;
   • изображения и другие медиа-файлы.

   Каждая следующая статья PDF-документа начинается с новой страницы. Статьи в PDF располагаются в том же порядке, что и в оглавлении.

Сборка

Настройка

1. Установите пакет @diplodoc/pdf-generator.

2. В файле toc.yaml добавьте секцию startPages для формирования титульных страниц.

3. Включите поддержку PDF в файле конфигурации .yfm:

   pdf:
     enabled: true
   

Генерация

1. Соберите проект документации:

   yfm -i . -o ./docs-output --pdf
   

   • -i . — путь к папке с исходниками (в примере — текущая папка);
   • -o ./docs-output — путь к папке для результатов сборки;
   • --pdf — флаг, включающий подготовку данных для генерации PDF; если поддержка PDF включена в .yfm, флаг передавать не требуется.

2. Запустите генератор PDF:

   npx -- @diplodoc/pdf-generator@latest -i ./docs-output
   

Стилизация

Вы можете изменить внешний вид PDF-документа с помощью CSS-стилей.

Фильтрация контента

Чтобы показывать или скрывать элементы только в PDF-версии, используйте пресеты.

1. Добавьте нужную переменную в presets.yaml:

   pdf:
     version: pdf
   

2. Используйте условие в тексте:

   {% if version == "pdf" %}
   
   Этот текст появится только в PDF-версии.
   
   {% endif %}