diff --git a/ru/guides/generate-pdf.md b/ru/guides/generate-pdf.md index c78ad05b..c41d6e9c 100644 --- a/ru/guides/generate-pdf.md +++ b/ru/guides/generate-pdf.md @@ -96,11 +96,11 @@ PDF-документ состоит из трех частей: ## Стилизация { #styles } -Вы можете изменить внешний вид PDF-документа с помощью [CSS-стилей](../style/css-js.md). +Вы можете изменить внешний вид PDF-документа с помощью [CSS-стилей](pdf-styles.md). {% note alert %} -Стили, добавленные внутри Markdown-файлов, Diplodoc удаляет при генерации PDF — это сделано в целях безопасности. +До версии 5.52.0 стили, добавленные внутри Markdown-файлов, удалялись при генерации PDF в целях безопасности. {% endnote %} diff --git a/ru/guides/pdf-styles.md b/ru/guides/pdf-styles.md new file mode 100644 index 00000000..4436a330 --- /dev/null +++ b/ru/guides/pdf-styles.md @@ -0,0 +1,460 @@ +# Пользовательские стили в PDF + +[PDF-версия документации](generate-pdf.md) собирается в три шага: + +1. Сборщик складывает контент всех статей в один JSON-файл. +1. Генератор PDF собирает из него отдельный HTML-документ. +1. Генератор печатает этот документ в PDF через браузер. + +Разметка этого HTML-документа отличается от разметки сайта: + +- часть классов сайта в нем отсутствует; +- уровни заголовков сдвинуты; +- к контенту применяются дополнительные стили печати. + +Поэтому селекторы, которые работают в обычной HTML-версии, в PDF могут не сработать. + +## Как стили попадают в PDF { #how-styles-apply } + +Отдельная настройка для PDF не нужна. [Стили, подключенные к проекту](../style/css-js.md) через блок `resources.style` конфигурационного файла `.yfm`, применяются и к сайту, и к PDF-документу. + +Всегда используйте флаг `--allow-custom-resources` при сборке: + +```bash +yfm build -i . -o ./docs-output --pdf --allow-custom-resources +``` + +Без флага `--allow-custom-resources` блок `resources.style` игнорируется целиком — стили не попадают ни в сборку сайта, ни в PDF. + +## Класс pdf { #pdf-class } + +Тег `` PDF-документа всегда имеет класс `pdf`: + +```html + +``` + +Этот класс больше нигде не используется, поэтому по нему можно отделить правила для PDF от общих правил проекта: + +```css +/* Правило действует только в PDF. */ +body.pdf main.yfm { + font-size: 14px; +} +``` + +Учитывайте ограничения: + +- Классы интерфейса сайта в PDF отсутствуют: `dc-doc-page`, `dc-doc-page__content`, `dc-toc`, `dc-mini-toc`, `dc-subnavigation`, `dc-controls` и другие. Селекторы на них в PDF не сработают. + + {% cut "Полный перечень классов" %} + + `App`, `Layout`, `Layout__body`, `Layout__content`, `desktop`, `col-reset`, + `dc-root_wide-format`, `dc-root_document-page`, + `dc-doc-layout`, `dc-doc-layout__center`, `dc-doc-layout__left`, + `dc-doc-layout__right`, `dc-doc-layout__toc`, `dc-doc-layout__desktop-only`, + `dc-doc-layout__mobile-only`, + `dc-doc-page`, `dc-doc-page__aside`, `dc-doc-page__body`, `dc-doc-page__content`, + `dc-doc-page__content-mini-toc`, `dc-doc-page__controls`, `dc-doc-page__main`, + `dc-doc-page__title`, `dc-doc-page__toc-nav-panel`, `dc-doc-page__under-title-info`, + `dc-doc-page__page-contributors`, `dc-doc-page-title`, + `dc-mini-toc*`, `dc-toc*`, `dc-toc-item__*`, + `dc-nav-toc-panel*`, `dc-subnavigation*`, `dc-sidebar-navigation*`, + `dc-controls*`, `dc-control`, `dc-share-button`, `dc-widgets`, + `pc-constructor-block`, `pc-constructor-block_type_page`, + `pc-block-base`, `pc-block-base_indentTop_0`, `pc-block-base_indentBottom_0`, + `pc-block-base_reset-paddings`, + `yfm-tooltip-live-region`. + + {% endcut %} + +- Тема Gravity в PDF не применяется. Класс `.g-root` на `` не назначается, поэтому переменные `--g-*` не действуют. Задавайте свойства напрямую. + +```css +/* Шрифт в PDF не изменится: переменных темы в PDF нет. */ +.g-root { + --g-font-family-sans: 'Georgia', serif; +} + +/* Шрифт изменится. */ +body.pdf, +body.pdf main.yfm { + font-family: 'Georgia', serif; +} +``` + +## Структура PDF-документа { #structure } + +PDF-документ состоит из титульных страниц, оглавления, основного контента и закрывающих страниц. + +```mermaid +graph TD + B["body.yfm.pdf"] --> S["Титульные страницы
.pdf-page-wrapper"] + B --> N["nav — оглавление"] + B --> M["main.yfm — контент"] + B --> E[".pdf-ending-pages
закрывающие страницы"] + N --> T[".toc"] + T --> H["h2[data-original-article]
пустой якорь"] + T --> U["ul > li > a | span"] + M --> A1["Статья 1
.pdf-page-wrapper"] + M --> A2["Статья N
.pdf-page-wrapper"] + A1 --> HA["h2[data-original-article]
заголовок статьи"] + A1 --> HB["h3 / h4 ..."] + E --> EW[".pdf-page-wrapper"] +``` + +Как это выглядит в разметке: + +```html + +
+ +
+ +
+
+

Заголовок статьи

+ +
+
+ +
+
+
+
+ +
+
+ +``` + +Селекторы для каждой части документа: + +#| +|| **Часть документа** | **Селектор** || +|| Титульные страницы | `body.pdf > .pdf-page-wrapper` || +|| Оглавление | `body.pdf > nav .toc` || +|| Статья | `body.pdf main.yfm > .pdf-page-wrapper` || +|| Закрывающие страницы | `body.pdf .pdf-ending-pages > .pdf-page-wrapper` || +|# + +{% note alert %} + +Титульные страницы, статьи и закрывающие страницы используют один класс `.pdf-page-wrapper` и различаются только положением в дереве: титульные страницы — прямые потомки `body`, статьи лежат внутри `main.yfm`. Селектор `.pdf-page-wrapper` без дочернего комбинатора `>` применится ко всем трем типам страниц. + +{% endnote %} + +### Титульные и закрывающие страницы { #start-end-pages } + +[Титульные и закрывающие страницы](generate-pdf.md#start-pages) задаются в файле `toc.yaml` в блоках `pdf.startPages` и `pdf.endPages`. + +Титульные страницы выбираются селектором по положению в дереве, закрывающие — по обертке `.pdf-ending-pages`: + +```css +/* Только титульные страницы. */ +body.pdf > .pdf-page-wrapper { + text-align: center; + padding-top: 200px; +} + +/* Только закрывающие страницы. */ +body.pdf .pdf-ending-pages > .pdf-page-wrapper { + text-align: center; + color: #808080; +} +``` + +### Оглавление { #toc } + +Оглавление — это отдельная страница внутри PDF, которую генератор создает из файла `toc.yaml` и размещает между титульными страницами и основным контентом. С боковым меню обычной HTML-версии оно не связано. + +Разметка оглавления: + +```html + +``` + +Особенности разметки: + +- `` — пункт со ссылкой на статью; +- `` — название раздела, объединяющего группу статей; +- у `` и `` могут быть классы `labeled` и `hidden` — они приходят из `toc.yaml`; +- вложенность любой глубины передается вложенными `