Структура страницы

Документация

Ниже представлено описание всех возможных блоков в исходнике страницы по порядку следования.

Этот порядок нужно сохранять при добавлении новых страниц, помня о культуре кода: отбитие пустыми строками разных по смыслу фрагментов кода, иерархия пробельных отступов слева при вкладывании блоков и т. п.

Подключение шаблона

{% extends template %}

Эта строка отвечает за включение тела страницы в шаблон, чтобы на выходе была полноценная HTML-страница. По умолчанию значение переменной template — /source/layouts/netbiblio/index.njk, но при необходимости можно включать отдельные страницы в другие шаблоны.

Настройки страницы

Задаются без какой-либо вложенности простым перечислением нужных опций. Некоторые настройки яляются обязательными:

Есть настройки, которые имеют значения по умолчанию, но могут переопределяться по необходимости:

О специфических настройках для каждого типа страниц поведано в разделах «Добавление автора» и «Добавление публикации».

Кастомный заголовок первого уровня

{% block heading %}{% endblock %}

По умолчанию заголовок формируется как <h1 class="art__title"> из переменной title или parentTitle (см. выше). Но иногда этого недостаточно, так как может понадобиться, например, поставить ударение, разрыв строки, мягкий перенос (категорически необходимо тестировать заголовки на ширине окна браузера 320px на предмет таких переносов в длинных словах). А в <title> документа или в строку оглавления (которые тоже основаны на переменной title) всё это добавлять нежелательно.

На помощь приходит блок heading, где всё с помощью того же <h1 class="art__title"> можно задать произвольное содержимое.

В отдельных случаях может понадобиться вывести презентационные три звёздочки, в таком случае заголовок требуется визуально скрыть: <h1 class="visually-hidden">.

В случае, когда изменения не затронут текст заголовка, а потребуется только обёртка или добавление чего-либо, следует использовать title вместо дублирования текста заголовка.

На авторских страницах этот блок позволит также добавить любой другой код между заголовком страницы и именем автора.

Предисловие

{% block preface %}{% endblock %}

Используется на страницах фрагментов произведений для того, чтобы вывести что-то (эпиграф, слоган, аннотацию, прочие вступления) между заголовком произведения (первого уровня) и заголовком главы (второго уровня).

Контент

{% block content %}{% endblock %}

Основное содержимое страницы. На авторской странице собирается до оглавлений.

Состоит из комбинации блоков, форматируемых определёнными стилевыми классами:

Классы можно миксовать. Например, стихотворение внутри фрагмента прозы является вставкой и может быть задано как art__poem art__ins.

Для ускорения вёрстки контента в проекте действует гибкая система фильтров, используемых по следующей схеме:

{% filter filterName %} Контент с инлайновыми тегами (явными или параметризованными). {% endfilter %}

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

Оглавления

{% block toc %}{% endblock %}

Используется на авторских страницах. По умолчанию выводит автоматически сгенерированное оглавление из произведений автора. Этот вариант рекомендуется оставлять только когда произведение одно или когда порядок получается ожидаемый.

Биография

{% block biography %}{% endblock %}

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

В конце его при наличии ссылок на литературные сайты автора можно вывести их списком authorLinks. Это макрос, который принимает либо одиночную строку (если ссылка одна), либо массив строк.