Download
Tutorials Github

Collapsible TOC Plugin

The Collapsible TOC plugin is a dynamic addition to Publii that modifies the Table of Contents (TOC) which can be generated in Publii's editors. The plugin does not create a TOC, but provides features to enhance accessibility and navigation of an existing TOC by making the TOC structure more semantic and introducing accessibility improvements like ARIA attributes.

Enabling the Plugin

To activate the Collapsible TOC plugin, navigate to the Tools & Plugins section of the Publii app, accessible via the left-hand menu. Here, you'll find a list of installed plugins. In this list, locate the Collapsible TOC tile and click on the switcher button in the bottom-left corner of the tile to activate the plugin.

Immediately upon activation, the plugin will modify any existing Tables of Contents on your site, adding collapsible functionality and a range of customizable features. However, the Collapsible TOC plugin also offers a number of settings that you can adjust to ensure it aligns with your requirements.

To access these settings, click on the Collapsible TOC tile again, but make sure to click anywhere except on the switcher button. This will open the settings screen where you can adjust various aspects of the plugin. Please note, this settings screen will not be accessible if the plugin is not enabled first.

Collapsible TOC Settings

When the Collapsible TOC plugin is activated, a settings screen becomes available. On this screen, you will find two main groups of settings that you can customize: "Options" and "Theme integration".

Options

The "Options" group provides control over the functionality and display of the collapsible Table of Contents. Here are the settings you can adjust within this group:

  • Toggle view: Controls the initial visibility state of the Table of Contents. When this option is enabled, the Table of Contents will be collapsed by default, but may be expanded or collapsed by the user. If this option is not enabled the TOC will be expanded by default, but can still be collapsed by the user if needed.
  • Toggle element: Select which element (the TOC header, the button, or both) will toggle the TOC subsection visibility when clicked.
  • Show/Hide button text: Customize the text that will be displayed on the button when the TOC is hidden or shown.
  • Automatic height: Enable this to adjust the TOC height dynamically based on the content; if not enabled, the height can be configured manually.
  • Custom maximum height: Only visible if the Automatic Height option is disabled. Allows a custom value for the maximum height of the TOC to be entered using pixels (px) or root element (rem) e.g. "500px", "20rem".

Theme Integration

The "Theme Integration" group focuses on how the TOC integrates with your Publii's theme. Here are the settings available within this group:

  • Header title: Customize the content of the TOC header; if left blank, the default content from the article in which the TOC appears will be used.
  • Heading level: Change the heading level for the TOC header. Publii generates an H3 heading by default, but here you can change it to any heading level from H1 to H6 as needed.
  • List Style: This option allows users to choose the numbering style for their Table of Contents. Select the appropriate option in the drop-down list to specify your preferred styling:
    • Decimal (1, 2, 3, 4, 5, ...):  decimal numbers.
    • Decimal Leading Zero (01, 02, 03, 04, 05, ...): decimal numbers with a leading zero for single-digit numbers.
    • Lower Roman (i, ii, iii, iv, v, ...): lowercase Roman numerals.
    • Upper Roman (I, II, III, IV, V, ...): uppercase Roman numerals.
    • Lower Alpha/Latin (a, b, c, d, e, ...): lowercase letters.
    • Upper Alpha/Latin (A, B, C, D, E, ...): uppercase letters.
    • Lower Greek (α, β, γ, δ, ε, ...): lowercase Greek letters.
    • None - no markers: this option will not apply any specific numbering or bullet style to the TOC entries.
  • Scroll padding top: Adjust the space between the top of the page and the section heading of the article once the user has clicked on an item in the TOC and the page scrolls to it. This can be helpful to ensure titles and content are not hidden under a header or navigation bar at the top of the screen. 

    Tip: Instead of using specific values such as "2rem" or "2vh", you can utilize a CSS variable like var(--navbar-height) if it's defined in your theme. Using this variable can help ensure that the jumped-to section will not be hidden underneath the top menu bar (header).

Remember to click on the "Save" button at the bottom-right of the screen after making any changes to these settings.

What code generates the Collapsible TOC?

After the plugin is activated, the structure of the HTML TOC generated by Publii is transformed to be more semantic and accessible. The standard unordered list (ul) is replaced with an ordered list (ol), denoting the hierarchy of the content. Furthermore, the nav element is used instead of the div to wrap the TOC, which improves the screen reader experience by indicating the navigational role of this section. The ARIA attributes aria-expanded and aria-hidden are used to improve accessibility by providing additional information about the state of the TOC.

Before enabling the plugin, your Table of Contents look like this:

<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>

After enabling the plugin:

<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>

Remember, by adjusting the settings in the plugin, you can customize how this structure behaves and looks in your Publii site.

Customizing the Table of Contents (TOC) Appearance

While your Publii site's theme primarily dictates the appearance of the Table of Contents (TOC), the 'Collapsible TOC' plugin provides additional control over the styling of the TOC toggle button (Hide/Show). This plugin gives you the ability to enhance the aesthetics of this feature.

These changes may be made in the Custom CSS tool, located in the Tools & Plugins section of the Publii main menu.

Available CSS variables

The 'Collapsible TOC' plugin for Publii offers support for CSS variables provided by your site's Publii theme. This compatibility helps ensure the styling of your table of contents (TOC) and the TOC toggle button remains consistent with the rest of your site's aesthetics.

However, there may be situations where you want the TOC to have a distinct appearance that doesn't mirror the rest of your site. In such cases, you can override the theme's CSS variables using the dedicated plugin classes. These dedicated classes allow you to customize the TOC independently of the theme's variables.

Here is a list of CSS variables you can use to adjust the appearance of the TOC. You can copy the entire block of code to your Custom CSS tool and modify it as per your needs. You also have the option to change only specific variables from the list.

: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;  
  }

Here's what each of these variables does:

  • --toc-link-color: This variable changes the color of the TOC links.
  • --toc-link-color-hover: This variable changes the color of the TOC links when they are hovered over, active, or in focus.
  • --toc-number-color: This variable modifies the color of the numbers or bullets in the TOC.
  • --toc-toggle-color: This variable changes the color of the TOC toggle button, specifically the square brackets.
  • --toc-toggle-link-color: This variable changes the color of the TOC toggle button link.
  • --toc-toggle-link-color-hover: This variable changes the color of the TOC toggle button link when it is hovered over.

Customizable CSS Classes for TOC Elements

In addition to CSS variables, the 'Collapsible TOC' plugin also provides specific CSS classes that target various elements of the Table of Contents. Using these classes, you can precisely adjust the appearance of individual components of the TOC to meet your site's styling requirements.

Here's a rundown of the classes you can use to style the 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 {}

What are you waiting for?

Start building your site today.

  1. 1 Download Publii
  2. 2 Write your content
  3. 3 Publish your site
Create website