Сворачиваемый оглавление

Складной плагин TOC

Плагин Collapsible TOC - это динамическое дополнение к Publii, которое изменяет оглавление (TOC), которое может быть сгенерировано в редакторах Publii. Плагин не создает ОГЛАВЛЕНИЕ, но предоставляет функции для улучшения доступности и навигации по существующему оглавлению, делая структуру оглавления более семантической и внедряя улучшения доступности, такие как атрибуты ARIA.

Включение плагина

Чтобы активировать плагин Collapsible TOC, перейдите в раздел "Инструменты и плагины" приложения Publii, доступный через меню слева. Здесь вы найдете список установленных плагинов. В этом списке найдите плитку сворачиваемого оглавления и нажмите на кнопку переключения в левом нижнем углу плитки, чтобы активировать плагин.

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

Чтобы получить доступ к этим настройкам, снова нажмите на плитку Сворачиваемого оглавления, но обязательно нажимайте где угодно, кроме кнопки переключения. Откроется экран настроек, где вы сможете настроить различные аспекты плагина. Пожалуйста, обратите внимание, что этот экран настроек будет недоступен, если плагин не будет включен первым.

Настройки сворачиваемого оглавления

Когда плагин сворачиваемого оглавления активирован, становится доступным экран настроек. На этом экране вы найдете две основные группы настроек, которые вы можете настроить: "Параметры" и "Интеграция темы".

Опции

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

  • Переключать вид: Управляет начальным состоянием видимости оглавления. Когда эта опция включена, оглавление будет свернуто по умолчанию, но может быть расширено или свернуто пользователем. Если эта опция не включена, оглавление будет развернуто по умолчанию, но все равно может быть свернуто пользователем при необходимости.
  • Переключить элемент: Выберите, какой элемент (заголовок оглавления, кнопка или оба вместе) будет переключать видимость подраздела оглавления при нажатии.
  • Показывать / скрывать текст кнопки: Настройте текст, который будет отображаться на кнопке, когда оглавление скрыто или показано.
  • Автоматическая высота: Включите этот параметр для динамической настройки высоты оглавления в зависимости от содержимого; если не включен, высоту можно настроить вручную.
  • Настраиваемая максимальная высота: отображается только в том случае, если опция Автоматическая высота отключена. Позволяет вводить пользовательское значение максимальной высоты оглавления с использованием пикселей (px) или корневого элемента (rem), например "500px", "20rem".

Интеграция с темой

Группа "Интеграция темы" посвящена тому, как TOC интегрируется с темой вашей публикации. Вот настройки, доступные в этой группе:

  • Заголовок заголовка: Настройте содержимое заголовка оглавления; если оставить его пустым, будет использоваться содержимое по умолчанию из статьи, в которой появляется ОГЛАВЛЕНИЕ.
  • Уровень заголовка: Измените уровень заголовка для заголовка оглавления. Publii по умолчанию генерирует заголовок H3, но здесь вы можете изменить его на любой уровень заголовка от H1 до H6 по мере необходимости.
  • Стиль списка: Эта опция позволяет пользователям выбирать стиль нумерации для своего оглавления. Выберите соответствующий параметр в раскрывающемся списке, чтобы указать предпочитаемый стиль:
    • Десятичные числа (1, 2, 3, 4, 5, ...): десятичные числа.
    • Десятичный начальный ноль (01, 02, 03, 04, 05, ...): десятичные числа с начальным нулем для однозначных чисел.
    • Строчные римские (i, ii, iii, iv, v, ...): строчные римские цифры.
    • Верхний римский (I, II, III, IV, V, ...): заглавные римские цифры.
    • Нижний алфавит /латиница (a, b, c, d, e, ...): строчные буквы.
    • Верхний алфавит / латиница (A, B, C, D, E, ...): заглавные буквы.
    • Строчный греческий (α, β, γ, δ, ε, ...): строчные греческие буквы.
    • Нет - нет маркеров: этот параметр не будет применять какую-либо определенную нумерацию или стиль маркирования к записям оглавления.
  • Прокрутка отступа сверху: Отрегулируйте расстояние между верхней частью страницы и заголовком раздела статьи, как только пользователь нажмет на элемент в оглавлении и страница перейдет к нему. Это может быть полезно для обеспечения того, чтобы заголовки и содержимое не были скрыты под заголовком или панелью навигации в верхней части экрана.

    Совет: Вместо использования определенных значений, таких как "2rem" или "2vh", вы можете использовать CSS-переменную типа var(--navbar-height), если она определена в вашей теме. Использование этой переменной может помочь гарантировать, что раздел перехода не будет скрыт под верхней строкой меню (header).

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

Какой код генерирует сворачиваемый TOC?

После активации плагина структура оглавления HTML, сгенерированного Publii, преобразуется, чтобы сделать ее более семантической и доступной. Стандартный неупорядоченный список (ul) заменен упорядоченным списком (ol), обозначающим иерархию содержимого. Кроме того, nav элемент используется вместо div для переноса оглавления, что улучшает работу программы чтения с экрана, указывая на навигационную роль этого раздела. Атрибуты ARIA aria-expanded и aria-hidden используются для улучшения доступности за счет предоставления дополнительной информации о состоянии оглавления.

Перед включением плагина ваше оглавление будет выглядеть следующим образом:

<div class="post__toc">
  <h3>Table of Contents</h3>
  <ul>
    <li><a href="#mcetoc_1h376r6091m">Introduction</a>
      <ul>
        <li><a href="#mcetoc_1h376r6091n">Chapter 1</a>
          <ul>
            <li><a href="#mcetoc_1h376r6091o">Section 1.1</a></li>
            <li><a href="#mcetoc_1h376r6091p">Section 1.2</a></li>
          </ul>
        </li>
        <li><a href="#mcetoc_1h376r6091q">Chapter 2</a></li>
      </ul>
    </li>
    <li><a href="#mcetoc_1h376r6091v">Summary</a></li>
  </ul>
</div>
 
После включения плагина:
<nav class="post__toc" aria-expanded="false">
  <h3 id="sublist-0" tabindex="0">
    <span>Table of Contents</span>
    <button class="post__toc-toogle">Show</button>
  </h3>
  <ol aria-hidden="true">
    <li><a href="#mcetoc_1h376r6091m">Introduction</a>
      <ol>
        <li><a href="#mcetoc_1h376r6091n">Chapter 1</a>
          <ol>
            <li><a href="#mcetoc_1h376r6091o">Section 1.1</a></li>
            <li><a href="#mcetoc_1h376r6091p">Section 1.2</a></li>
          </ol>
        </li>
        <li><a href="#mcetoc_1h376r6091q">Chapter 2</a></li>
      </ol>
    </li>
    <li><a href="#mcetoc_1h376r6091v">Summary</a></li>
  </ol>
</nav>
 
Помните, изменяя настройки в плагине, вы можете настроить поведение и внешний вид этой структуры на вашем сайте Publii.

Настройка внешнего вида оглавления (TOC)

В то время как тема вашего сайта Publii в первую очередь определяет внешний вид оглавления (TOC), плагин "Сворачиваемого оглавления" предоставляет дополнительный контроль над стилем кнопки переключения оглавления (Скрыть / Показать). Этот плагин дает вам возможность улучшить эстетику этой функции.

Эти изменения могут быть внесены с помощью пользовательского инструмента CSS, расположенного в разделе Инструменты и плагины главного меню Publii.

Доступные переменные CSS

Плагин 'Collapsible TOC' для Publii предлагает поддержку CSS-переменных, предоставляемых темой Publii вашего сайта. Такая совместимость помогает гарантировать соответствие стиля вашего оглавления (TOC) и кнопки переключения TOC остальной эстетике вашего сайта.

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

Вот список переменных CSS, которые вы можете использовать для настройки внешнего вида оглавления. Вы можете скопировать весь блок кода в свой пользовательский инструмент CSS и изменить его в соответствии с вашими потребностями. У вас также есть возможность изменять только определенные переменные из списка.

:root {    
    --toc-link-color: red;
    --toc-link-color-hover: black;
    --toc-number-color: black;
    --toc-toggle-color: black;
    --toc-toggle-link-color: red; 
    --toc-toggle-link-color-hover: red;  
  }
 

Вот что делает каждая из этих переменных:

  • --toc-link-color: Эта переменная изменяет цвет ссылок на оглавление.
  • --toc-link-color-hover: Эта переменная изменяет цвет ссылок оглавления, когда они наведены курсором, активны или находятся в фокусе.
  • --toc-number-color: Эта переменная изменяет цвет цифр или маркеров в оглавлении.
  • --toc-toggle-color: Эта переменная изменяет цвет кнопки переключения TOC, в частности квадратных скобок.
  • --toc-toggle-link-color: Эта переменная изменяет цвет ссылки на кнопку переключения оглавления.
  • --toc-toggle-link-color-hover: Эта переменная изменяет цвет ссылки на кнопку переключения оглавления при наведении на нее курсора мыши.

Настраиваемые CSS-классы для элементов TOC

В дополнение к переменным CSS, плагин 'Collapsible TOC' также предоставляет специальные классы CSS, предназначенные для различных элементов оглавления. Используя эти классы, вы можете точно настроить внешний вид отдельных компонентов TOC в соответствии с требованиями к стилю вашего сайта.

Вот краткое описание классов, которые вы можете использовать для оформления TOC:

/* Main container for the Table of Contents */
.post__toc {}

/* Table of Contents when it's expanded */
.post__toc[aria-expanded="true"] {}

/* Table of Contents when it's collapsed */
.post__toc[aria-expanded="false"] {}

/* The hide/show for showing and hiding the Table of Contents */
.post__toc-toggle {}
    
/* Styling for the hide/show button when hovered, active or focused */
.post__toc-toggle:hover, 
.post__toc-toggle:active, 
.post__toc-toggle:focus {}

/* Styling for the square brackets elements before and after the hide/show button */
.post__toc-toggle::before, 
.post__toc-toggle::after {}
    
/* Styling for the table of contents header, which contains the text and hide/show button. 
   The tag (H3 here) could vary based on the option chosen in the plugin settings, and can range from H1 to H6. */
.post__toc h3 {}

/* The ordered list (ol) directly under the main container */
.post__toc > ol {}

/* The ordered list when it's visible */
.post__toc > ol[aria-hidden="false"] {}

/* The ordered list when it's hidden */
.post__toc > ol[aria-hidden="true"] {}

/* All ordered lists (ol) in the Table of Contents */
.post__toc ol {}

/* List items (li) in the ordered list (ol) */
.post__toc ol li {}
    
/* Styling for the anchor links (a) in the table of contents */
.post__toc a {}

/* Styling for the numbers appearing before the anchor links */
.post__toc a::before {}
Powered by Publii

Subscribe

Get the latest news, updates and more delivered directly to your email inbox

...