Модуль Содержание автоматически собирает список заголовков из текста записи и выводит навигацию по статье. Это помогает читателю быстрее понять структуру материала и перейти к нужному разделу.
Содержание можно вывести автоматически внутри текста или вставить вручную в нужное место через шорткод [toc].
Как работает модуль
Модуль анализирует заголовки в содержимом записи, формирует список пунктов и добавляет якорные ссылки на найденные разделы. Если у заголовка уже есть атрибут id, он будет использован. Если якоря нет, модуль может создать его автоматически.
Сейчас модуль работает для отдельных записей типа post. Если на странице найдено меньше заголовков, чем указано в настройке Минимум заголовков, содержание не выводится.
Текст пункта содержания берется из текста заголовка. Если у заголовка задан атрибут title, для пункта содержания будет использовано его значение.
Где находятся настройки
Открыть настройки модуля можно в кастомайзере: Внешний вид > Настроить > Модули > Содержание.
Как вывести содержание
Если модуль включен, содержание может выводиться автоматически в тексте записи. Точка вывода задается через настройку Позиция вывода.
Если нужно поставить содержание вручную, используйте шорткод [[toc]] в нужном месте контента. Если шорткод уже добавлен в запись, автоматическая вставка второго блока содержания не выполняется.
Если содержание выводится, например, в сайдбаре и его не нужно показывать внутри записи автоматически, это можно отключить в настройках записи: Типы записей > Запись. При этом шорткод [[toc]] при ручной вставке продолжит работать.
Настройки модуля
Включить содержание
Включает или полностью отключает модуль.
Заголовок
Задает заголовок, который отображается над блоком содержания. По умолчанию используется текст Содержание, но его можно заменить на любой свой.
Минимум заголовков
Определяет минимальное количество подходящих заголовков, после которого содержание будет показано. Если заголовков меньше, блок не выводится.
Уровни заголовков
Позволяет выбрать, какие заголовки включать в содержание. Например, можно выводить только H2 или использовать сразу несколько уровней, например H2 и H3.
Позиция вывода
Определяет место автоматического вывода содержания в записи.
- В начале статьи — содержание выводится перед основным текстом.
- После первого абзаца — содержание вставляется после первого абзаца. Если подходящий абзац не найден, модуль попробует поставить блок перед первым подходящим заголовком.
- Перед первым заголовком — содержание вставляется перед первым подходящим заголовком. Если такой заголовок не найден, блок будет добавлен в начало текста.
Показывать нумерацию
Добавляет нумерацию перед пунктами содержания. Это особенно полезно для длинных структурированных статей.
Разрешить сворачивание
Добавляет кнопку, с помощью которой посетитель может свернуть или развернуть содержание.
Свернуто по умолчанию
Показывает содержание в свернутом виде при первой загрузке страницы. Настройка имеет смысл, если включен параметр Разрешить сворачивание.
Иконка кнопки сворачивания
Позволяет выбрать иконку для кнопки сворачивания содержания.
Цвет фона
Задает цвет фона или градиент блока содержания.
Цвет текста
Задает цвет текста внутри блока содержания.
Скругление углов
Управляет скруглением углов блока содержания.
Колонки
Позволяет выбрать количество колонок для списка содержания на разных устройствах. Если пунктов много, несколько колонок помогают сделать блок компактнее.
Хуки
Модуль содержит набор хуков для изменения контента, списка пунктов и правил вывода. Подробнее о хуках WordPress можно почитать в официальной документации.
wpbox/toc/content
Позволяет изменить исходный контент, по которому строится содержание.
add_filter( 'wpbox/toc/content', function( $content, $post_id ) {
if ( 123 === (int) $post_id ) {
$content .= '<h2>Дополнительный раздел</h2>';
}
return $content;
}, 10, 2 );wpbox/toc/is_process_shortcodes
Определяет, нужно ли обрабатывать шорткоды перед поиском заголовков.
add_filter( 'wpbox/toc/is_process_shortcodes', '__return_false' );wpbox/toc/is_process_blocks
Определяет, нужно ли обрабатывать Gutenberg-блоки перед поиском заголовков.
add_filter( 'wpbox/toc/is_process_blocks', '__return_false' );wpbox/toc/tags
Позволяет изменить список уровней заголовков, которые будут учитываться при построении содержания.
add_filter( 'wpbox/toc/tags', function( $tags ) {
return array( 'h2', 'h3', 'h4' );
} );wpbox/toc/min_headings
Позволяет программно изменить минимальное количество заголовков для показа содержания.
add_filter( 'wpbox/toc/min_headings', function( $min_headings ) {
return 2;
} );wpbox/toc/items
Позволяет изменить уже собранный массив пунктов содержания перед выводом.
add_filter( 'wpbox/toc/items', function( $items, $post_id ) {
return array_values( array_filter( $items, function( $item ) {
return 'h2' === $item['tag'];
} ) );
}, 10, 2 );wpbox/toc/apply_missing_anchors
Определяет, нужно ли автоматически добавлять якоря к заголовкам, у которых нет id.
add_filter( 'wpbox/toc/apply_missing_anchors', '__return_false' );wpbox/toc/is_render_shortcode
Позволяет полностью запретить вывод содержания через шорткод.
add_filter( 'wpbox/toc/is_render_shortcode', '__return_false' );CSS-переменные
Модуль поддерживает CSS-переменные для более гибкой настройки внешнего вида. Это удобно, если нужно изменить отступы, цвета или количество колонок вне стандартных настроек кастомайзера. Подробнее о принципе работы таких переменных можно прочитать в отдельной статье: CSS переменные в WPBox.
--wpbox-toc-bg— фон блока содержания.--wpbox-toc-text-color— цвет текста блока содержания.--wpbox-toc-margin-top— верхний отступ блока.--wpbox-toc-margin-bottom— нижний отступ блока.--wpbox-toc-border-radius— скругление углов блока.--wpbox-toc-columns— количество колонок в списке содержания.