Generate a table of contents for the pages of your Pico site.
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.
- 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.
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
pluginsdirectory- download the latest release
- extract the archive into your
pluginsdirectory - rename the plugin's folder to
TableOfContents
The structure should be as follows
plugins
└───TableOfContents
│ style.css
│ TableOfContents.php
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.
In your template files, add a link to the plugin stylesheet in the head section:
<!-- index.twig and/or page.twig, etc. -->
<head>
...
<!-- Table Of Contents -->
<link rel="stylesheet" type="text/css" href="{{ plugins_url }}/TableOfContents/style.css" />
...
</head>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: 2min_level- Minimum header level displayed in the ToC. - Default value: 1max_level- Maximum header level displayed in the ToC. - Default value: 5tag- 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:
##
# Table Of Contents Plugin
#
TOC:
min_headers: 2
min_level: 1
max_level: 5
tag: ol
style: none
heading: ContentsThis 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).
{{ toc }}- The HTML code of the ToC for the current page.
---
Title: Table Of Contents Example
Description:
TOC:
max_level: 3
style: numbers
heading: Example of Table of Contents
---
Here is the Table Of Contents generated for the current page:
[toc]
# This is a `<h1>`
Lorem ipsum dolor sit amet, consectetur adipisici elit, sed eiusmod tempor incidunt ut labore et dolore magna aliqua.
## And this is a `<h2>`
Lorem ipsum dolor sit amet, consectetur adipisici elit, sed eiusmod tempor incidunt ut labore et dolore magna aliqua.
### Then, you can see a `<h3>`
Lorem ipsum dolor sit amet, consectetur adipisici elit, sed eiusmod tempor incidunt ut labore et dolore magna aliqua.
#### But `<h4>` are not visible in the Table Of Contents
Lorem ipsum dolor sit amet, consectetur adipisici elit, sed eiusmod tempor incidunt ut labore et dolore magna aliqua.
### An other `<h3>`
Lorem ipsum dolor sit amet, consectetur adipisici elit, sed eiusmod tempor incidunt ut labore et dolore magna aliqua.
# Again a `<h1>`
Lorem ipsum dolor sit amet, consectetur adipisici elit, sed eiusmod tempor incidunt ut labore et dolore magna aliqua.
## An other `<h2>`
Lorem ipsum dolor sit amet, consectetur adipisici elit, sed eiusmod tempor incidunt ut labore et dolore magna aliqua.
## And the last `<h2>`
Lorem ipsum dolor sit amet, consectetur adipisici elit, sed eiusmod tempor incidunt ut labore et dolore magna aliqua.
- 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.
- Replaces the
- New features
- Add the
{{ toc }}Twig variable.
- Add the
Pico Table Of Contents Plugin is open-source licensed under the MIT License. See LICENSE for details.