Carew. Вступительный текст без "front matter"

Зачем мне понадобился вступительный текст#

Генератор статических сайтов Carew, по моему скромному мнению, "из коробки" поддерживает почти все, что нужно для ведения среднестатистического блога — посты, страницы, категории, теги и темы. Списки категорий, к сожалению, а может к счастью, представлены достаточно аскетично — просто список ссылок на материалы, где анкорами являются заголовки. Но, многим, в том числе и мне, этого покажется мало. Просматривая категорию, под заголовком, я ожидаю увидеть намек на то, о чем же все таки идет речь.

Как отображать вступительный текст#

Итак, первое, что придет на ум разработчику, использующему любой генератор статических сайтов — это front matter. Решение простое и даже логичное, но попытка использовать там форматирование заканчивается неудачей. Аналогично для нескольких строк текста.

Раз front matter для наших целей не подходит, будем использовать область основного текста. Просто введем понятие разделителя между основным и вступительным содержимым. Пусть это будет HTML комментарий такого вида:

<!--more-->

Теперь нужно сообщить движку о том, что нужно как-то обрабатывать новоявленный разделитель. Так как нашей изначальной целью является список документов, создаем/открываем файл layouts/blocks.html.twig и находим в нем блок documents. Именно здесь и описан нужный нам вывод.

{% block documents %}
{% spaceless -%}
    <ul class="{% block ul_class '' %}">
        {% for document in documents %}
            <li class="{% block li_class '' %}">
                {% block document_list %}
                    <a href="{{ render_document_path(document) }}">
                        {{ render_document_title(document) }}
                    </a>
                {% endblock %}
            </li>
        {% endfor %}
    </ul>
{%- endspaceless %}
{% endblock %}

Для упрощения, давайте выводить вступление прямо под ссылкой.

<a href="{{ render_document_path(document) }}">
    {{ render_document_title(document) }}
</a>
{{ render_document_intro(document) }}

Понять, почему функция вывода вступления называна именно render_document_intro можно, взглянув на этот раздел документации, я же просто представлю вам свой вариант реализации данного блока:

{% block document_intro %}
    {% spaceless -%}
        {% set parts = document.body|split('<!--more-->') %}
        {% if 2 == parts|length %}
            {{ parts[0]|raw }}
        {% endif %}
    {%- endspaceless %}
{% endblock %}

Алгоритм элементарен — разделяем текст по <!--more--> и выводим первую часть. Надеюсь, кому-нибудь прогодится.