Кастомизация сборки HTML
Чтобы привести внешний вид HTML-документации в соответствие с вашим фирменным стилем, необходимо создать тему оформления HTML. Для начала достаточно создать шаблон для рендеринга страниц, при необходимости приложив к нему готовые статические файлы. Затем для более тонкого управления внешним видом элементов можно включить в тему плагин на языке Python. Также возможна автоматическая компиляция стилей из файлов SASS.
Собирака загружает файлы из темы оформления, указанной в настройке web.theme. Все файлы, кроме шаблона для рендеринга страниц, опциональны.
Документация, которую вы читаете сейчас, собрана с темой sobiraka2025. Можете найти её в исходниках Собираки и изучить как пример, когда будете разрабатывать собственную тему оформления.
Шаблон для рендеринга страниц #
Файл web.html используется как шаблон при рендеринге каждой страницы документации. Это единственный файл, обязательный для любой темы оформления.
Для превращения шаблона в конечную HTML-страницу используется шаблонизатор Jinja. Руководство по синтаксису шаблонизатора можно найти на его официальном сайте: Template Designer Documentation.
Шаблону доступен набор переменных и функций, описанных в разделе API для шаблонов. В частности, при разработке новой темы настоятельно рекомендуется подставлять в тег <head> содержимое переменной head: она может содержать скрипты и стили, необходимые для работы поиска по документации.
В Собираке отключена поддержка стандартного синтаксиса комментариев внутри шаблона Jinja, чтобы избежать коллизии с идентификаторами заголовков в Markdown. Чтобы добавить комментарий внутрь шаблона, используйте синтаксис со сдвоенными фигурными скобками: {{# Комментарий #}}.
Статические файлы #
Директория _static должна содержать файлы, которые необходимы для правильного отображения темы в браузере. Чаще всего к таким файлам относятся стили, скрипты, изображения и шрифты.
В директорию с готовой документацией будет вложена полная копия директории _static. Относительный путь к ней будет доступен шаблону через переменную STATIC. Например, {{STATIC}}/logo.svg преобразуется в путь наподобие ../_static/logo.svg.
Плагин для обработки страниц #
В файле extension.py может быть определён обработчик страниц — код на Python для дополнительной обработки содержимого перед рендерингом. В ряде случаев это позволяет снять часть ответственности со скриптов, выполняющихся в браузере, и перенести их логику в код, выполняющийся в момент сборки.
Класс плагина должен наследоваться от класса WebProcessor. Плагин имеет почти неограниченные возможности в рамках обработки отдельной страницы, см. API для обработчиков.
Пример. Предположим, что по задумке дизайнера горизонтальные и вертикальные изображения должны быть по-разному оформлены.
Добавив соответствующие проверки в код на Python, разработчик темы может добавить каждому блоку подходящий класс на этапе сборки документации. Аналогичный код в браузере пользователя не смог бы выполняться до загрузки изображений.
Файлы стилей SASS #
Некоторые темы оформления (в том числе фирменная тема sobiraka2025) используют препроцессор SASS и его языки SASS или SCSS для генерации стилей. Собирака запускает генерацию в рамках процесса сборки документации. Обратите внимание, что необходимая для этого команда sass не входит в Собираку и должна быть установлена отдельно.
Исходный файл стиля должен располагаться по адресу sass/web.sass или sass/web.scss в директории темы. При необходимости он может подключать другие файлы с помощью SASS-директивы @use. Сгенерированный стиль будет размещён по адресу _static/theme.css в выходной директории.
Тема может включать в себя несколько вариантов оформления в поддиректории _flavors. Для выбора нужного варианта следует указать его название в настройке pdf.theme.flavor. Разработчик темы должен подключить выбранный пользователем вариант с помощью конструкции @use 'flavor'. Какие именно SASS-переменные и миксины возможно переопределить таким способом, зависит от конкретной темы.
Также возможно добавление файлов SASS/SCSS из директории проекта. Файлы, указанные в pdf.theme.customization, участвуют в генерации стиля _static/theme.css наравне с собственными файлами темы. Из файлов, указанных в pdf.custom_styles, генерируются дополнительные CSS-стили.
Теги <link> со ссылками на все собранные стили CSS будут автоматически включены в переменную head, которую рекомендуется подключить в HTML-шаблон, см. API для шаблонов.