Конструкции Jinja

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

Переменные #

Установите {{ PRODUCT }} {{ VERSION }} с сайта {{ WEBSITE }}.

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

По умолчанию доступны переменные из списка ниже. Вы можете добавить к этому списку собственные переменные на уровне тома или проекта с помощью настройки variables.

  • project — текущий проект.

  • document — текущий документ.

  • page — текущая страница.

  • LANG — язык текущего документа.

  • HTML — во время сборки в HTML принимает значение True, иначе — False.

  • PDF — во время сборки в PDF принимает значение True, иначе — False.

API Собираки может дорабатываться и меняться от проекта к проекту.

Условия #

{% if PDF %}
    Актуальная версия документации всегда доступна на сайте {{ WEBSITE }}.
{% end %}

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

Так, в примере выше внутрь PDF-документации вставляется ссылка на HTML-документацию, чтобы у читателя потенциально устаревшего файла была возможность перейти к более свежей версии.

Также конструкция может быть полезна для вставки дополнительных материалов, которые работают только в одном из форматов — например, видеороликов. Обратите внимание, что в таких ситуациях вы также можете использовать низкоуровневый код в Pandoc Markdown.

Инклюды #

{% include 'be-careful-when-performing-this-action.md' %}

Конструкция include позволяет включить внутрь текущего документа фрагмент, хранящийся в отдельном файле. Включаемый файл должен храниться в директории, указанной в настройке paths.partials. Включаемый файл должен использовать тот же синтаксис, что и текущий файл.

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

Если текст фрагмента должен быть немного разным в разных местах, вы можете использовать в нём переменные Jinja. Чтобы задать переменные для фрагмента, оберните include в конструкцию with:

{% with %}
    {% set action = 'Удаление профиля' %}
    {% include 'be-careful-when-performing-this-action.md' %}
{% endwith %}

Комментарии #

Любой текст между конструкциями {{# и #}} считается комментарием. Шаблонизатор полностью игнорирует эти комментарии и исключает их из конечного файла.

Например, с помощью комментариев Jinja вы можете оставлять замечания, которые важно сообщить коллегам, работающим над текстом, но скрыть от конечного читателя документации. В отличие от обычных HTML-комментариев, читатель не сможет увидеть комментарии Jinja, даже если исследует исходный код готовой страницы.

Обратите внимание, что синтаксис, включённый в Собираке, отличается от стандартного синтаксиса комментариев в Jinja: в Собираке используются двойные фигурные скобки вместо одинарных. Это сделано из-за того, что вариант с одинарными скобками привёл бы к некорректной обработке идентификаторов подзаголовков в Markdown.

Плеер поддерживает большинство популярных аудиоформатов.
{{# избегаем слова «все», потому что flac пока не поддерживается #}}