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

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

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

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

{% extends template %}

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

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

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

title — имя автора или название произведения (в зависимости от типа страницы).
pubdate — дата публикации произведения в формате DD.MM.YYYY. Для авторской страницы дублируется дата его первой публикации в «Netbiblio».

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

pageDescription — описание страницы (имеется по умолчанию для всех типов страниц, но может быть задано здесь для конкретной страницы).
prev и next — предыдущая и следующая ссылки навигационного ринга в формате page (то есть без учёта корневой части и .html). Задаётся автоматически только для некрайних элементов коллекций. Коллекцией считается список страниц в каталоге автора, названия которых состоят из общей части, дефиса и числового индекса. Если индекс не равен единице или длине коллекции, система знает, что для получения смежных ссылок нужно прибавить к текущему индексу единицу (или отнять от него). Для первой страницы коллекции нужно обязательно задать prev, для крайней — next. Для одиночных страниц произведений и для страниц авторов оба параметра обязательны.
prevTitle — текст всплывающей подсказки и доступной (a11y) надписи для предыдущей ссылки навигационного ринга.
nextTitle — текст всплывающей подсказки и доступной надписи для следующей ссылки навигационного ринга.
tocHref — ссылка на вышерасположенный уровень навигационного ринга. По умолчанию ведёт на список авторов на главной странице. Для произведений указывает на авторскую страницу, причём для коллекций — с добавлением якоря на оглавление коллекции (для этого нужно правильно его составить).
tocTitle — текст ссылки на вышерасположенный уровень навигационного ринга.
openGraphImg — изображение для OpenGraph. Применяется каскадно: если оно задано для конкретной страницы — применяется. Если для страницы публикации изображение не задано, но задано для соответствующей авторской страницы, будет применено последнее. Если ничего не задано — применяется изображение по умолчанию. Предполагается, что при кастомном переопределении этого параметра для публикации или для автора переопределены и связанные: openGraphImgType, openGraphImgWidth, openGraphImgHeight, openGraphImgAlt. Если данное изображение используется и в контенте, целесообразно параметризовать его подключение указанными переменными.

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

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

{% 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__subtitle — заголовок главы, подзаголовок, заголовок второго уровня.
art__prose — основной художественный текст, абзацы без отступов, выравнивание по ширине с подготовленному к будущей поддержке браузерами функционалу переносов. Красная строка в 2rem. Слегка увеличенный размер в 1.125rem — для сочетания шрифта с насечками с основным шрифтом.
art__poem — такой же шрифт, но абзацы разделены пустыми строками, переход на строку без отделения выполняется <br>. Красной строки нет.
art__short — центрированный короткий текст.
art__ins — (вставка) — уменьшенного размера дополнительный блок.

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

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

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

prose — размечает текст абзацами, обернутыми в контейнер с классом art__prose.
prose("quote") — работает, как prose, но контейнер — <blockquote>. Имя автора извлекается из последнего параграфа.
prose("short") — оборачивает текст как есть а один абзац с классом art__prose (рекомендуется использовать, если внутри фильтра всегод один параграф, для борьбы с лишними обёртками).
short — оборачивает текст как есть а один абзац с классом art__short (рекомендуется использовать, если внутри фильтра всегод один параграф, для борьбы с лишними обёртками).
poem — размечает строфы абзацами, обернутыми в контейнер с классом art__poem. Строки отбиваются с помощью <br>.
poem("quote") — работает, как poem, но контейнер — <blockquote>. Имя автора извлекается из последнего параграфа.
poem("raw") — также размечает строфы абзацами, но в контейнер не оборачивает.
ins — добавляет к контейнеру своего содержимого класс art__ins (можно делать вставки вкладыванием в этот фильтр фильтров prose или poem). При отсутствии контейнера с классом — превращает строки в абзацы и оборачивает их в div с классом art__ins.
epigraph — добавляет к контейнеру своего содержимого класс art__epigraph, поэтому используется только при наличии контейнера с классом. Рекомендуется делать вставки вкладыванием в этот фильтр фильтров prose("quote") или poem("quote").

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

Оглавления

{% block toc %}{% endblock %}

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

Биография

{% block biography %}{% endblock %}

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

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