Создание 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-документа начинается с новой страницы.

Сборка

Настройка

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 — путь к папке для результатов сборки.

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 %}