Download the PHP package iridescent-dev/pico-toc-plugin without Composer

Pico Table Of Contents Plugin

Generate a table of contents for the pages of your Pico site.

• Usage
• Getting Started
  • Install
  • Update your theme
  • Configuration settings
  • Template variables defined for Twig
• Example
  • The index.md file
  • Screenshot
• Changelog
  • 2.0
• License

Usage

Automatically generates a table of contents (ToC) based on the <h1> to <h6> tags.

In your Markdown file, simply add the [toc] marker where you want the ToC to be inserted. This marker must be added for each page you want. You must add a new line before and after the marker.

You can also add the ToC directly in your theme by using the {{ toc }} Twig variable in your template.

See the configuration settings section to see the available options.

Getting Started

• Install the plugin;
• Update your theme to add the plugin stylesheet in your Twig templates;
• Change default configuration settings;
• Use it by adding the [toc] marker or the {{ toc }} Twig variable where you want the ToC to appear on your page.

Install

Add the plugin in the plugins directory of your Pico installation (e.g. /var/www/html/pico/plugins/)

• using Composer composer require iridescent-dev/pico-toc-plugin
• or manually by uploading the plugin’s files to your plugins directory
  • download the latest release
  • extract the archive into your plugins directory
  • rename the plugin's folder to TableOfContents

The structure should be as follows

Pico Table Of Contents plugin requires PHP >=7.0.

We always recommend you to use Composer whenever possible, because it makes updating the plugin way easier.

Update your theme

In your template files, add a link to the plugin stylesheet in the head section:

Configuration settings

You can change the default configuration by adding values to your config file. Here are the options available and what they do.

• min_headers - Minimum number of headers required to display the ToC. - Default value: 2
• min_level - Minimum header level displayed in the ToC. - Default value: 1
• max_level - Maximum header level displayed in the ToC. - Default value: 5
• tag - The tag used for the list. - Default value: ol
  • ol (ordered list)
  • ul (unordered list)
• style - The css style applied to the list. - Default value: none
  • numbers (1, 1.1, 1.2, ...)
  • bullets (● ○ ■)
  • none (no item marker is shown)
  • default (the default css style applied to lists)
• heading - Heading text, if a heading for the ToC is desired. - Default value: (unset)

For reference, these values are set in config/config.yml using the following format:

This configuration will be applied to the entire site, but it's also possible to override it for a specific page by adding the Meta headers with the same format (see the example).

Template variables defined for Twig

• {{ toc }} - The HTML code of the ToC for the current page.

Example

The index.md file

Screenshot

Changelog

2.0

• Breaking changes
  • Replaces the <toc/> element with the [toc] marker to be compatible with Nextcloud.
  • Renames and restructures configuration options.
  • Override the configuration for a specific page using Meta headers instead of tag attributes.
• New features
  • Add the {{ toc }} Twig variable.

License

Pico Table Of Contents Plugin is open-source licensed under the MIT License. See LICENSE for details.