PHPackages                             iridescent-dev/pico-toc-plugin - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. iridescent-dev/pico-toc-plugin

ActivePico-plugin[Utility & Helpers](/categories/utility)

iridescent-dev/pico-toc-plugin
==============================

A Table Of Contents plugin for Pico CMS.

2.1(4y ago)7874[4 issues](https://github.com/iridescent-dev/pico-toc-plugin/issues)[6 PRs](https://github.com/iridescent-dev/pico-toc-plugin/pulls)MITPHPPHP >=7.0

Since Sep 29Pushed 2y ago3 watchersCompare

[ Source](https://github.com/iridescent-dev/pico-toc-plugin)[ Packagist](https://packagist.org/packages/iridescent-dev/pico-toc-plugin)[ Docs](https://github.com/iridescent-dev/pico-toc-plugin)[ RSS](/packages/iridescent-dev-pico-toc-plugin/feed)WikiDiscussions main Synced 1w ago

READMEChangelog (8)Dependencies (1)Versions (8)Used By (0)

Pico Table Of Contents Plugin
==============================

[](#pico-table-of-contents-plugin-)

Generate a table of contents for the pages of your [Pico](http://picocms.org) site.

- [Usage](#usage)
- [Getting Started](#getting-started)
    - [Install](#install)
    - [Update your theme](#update-your-theme)
    - [Configuration settings](#configuration-settings)
    - [Template variables defined for Twig](#template-variables-defined-for-twig)
- [Example](#example)
    - [The `index.md` file](#the-indexmd-file)
    - [Screenshot](#screenshot)
- [Changelog](#changelog)
    - [2.0](#20)
- [License](#license)

Usage
=====

[](#usage)

Automatically generates a table of contents (ToC) based on the `` to `` 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](#configuration-settings) section to see the available options.

Getting Started
===============

[](#getting-started)

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

Install
-------

[](#install)

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

- using [Composer](https://getcomposer.org/) `composer require iridescent-dev/pico-toc-plugin`
- or manually by uploading the plugin’s files to your `plugins` directory
    - [download the latest release](https://github.com/iridescent-dev/pico-toc-plugin/releases/latest)
    - extract the archive into your `plugins` directory
    - 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.

Update your theme
-----------------

[](#update-your-theme)

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

```

    ...

    ...

```

Configuration settings
----------------------

[](#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:

```
##
# Table Of Contents Plugin
#
TOC:
  min_headers: 2
  min_level: 1
  max_level: 5
  tag: ol
  style: none
  heading: Contents
```

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](#example)).

Template variables defined for Twig
-----------------------------------

[](#template-variables-defined-for-twig)

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

Example
=======

[](#example)

The `index.md` file
-------------------

[](#the-indexmd-file)

```
---
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 ``
Lorem ipsum dolor sit amet, consectetur adipisici elit, sed eiusmod tempor incidunt ut labore et dolore magna aliqua.

## And this is a ``
Lorem ipsum dolor sit amet, consectetur adipisici elit, sed eiusmod tempor incidunt ut labore et dolore magna aliqua.

### Then, you can see a ``
Lorem ipsum dolor sit amet, consectetur adipisici elit, sed eiusmod tempor incidunt ut labore et dolore magna aliqua.

#### But `` 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 ``
Lorem ipsum dolor sit amet, consectetur adipisici elit, sed eiusmod tempor incidunt ut labore et dolore magna aliqua.

# Again a ``
Lorem ipsum dolor sit amet, consectetur adipisici elit, sed eiusmod tempor incidunt ut labore et dolore magna aliqua.

## An other ``
Lorem ipsum dolor sit amet, consectetur adipisici elit, sed eiusmod tempor incidunt ut labore et dolore magna aliqua.

## And the last ``
Lorem ipsum dolor sit amet, consectetur adipisici elit, sed eiusmod tempor incidunt ut labore et dolore magna aliqua.

```

Screenshot
----------

[](#screenshot)

 [![](Screenshot.png "Screenshot")](Screenshot.png)

Changelog
=========

[](#changelog)

2.0
---

[](#20)

- Breaking changes
    - Replaces the `` 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
=======

[](#license)

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

###  Health Score

24

—

LowBetter than 32% of packages

Maintenance9

Infrequent updates — may be unmaintained

Popularity17

Limited adoption so far

Community14

Small or concentrated contributor base

Maturity50

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 89.3% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~22 days

Total

6

Last Release

1581d ago

Major Versions

1.5 → 2.02021-11-15

PHP version history (2 changes)1.2PHP >=7.4

1.5PHP >=7.0

### Community

Maintainers

![](https://www.gravatar.com/avatar/50806ed937e631b9c169b172b0ee572df9407ea9417921944d2e32b34696ebe4?d=identicon)[iridescent-dev](/maintainers/iridescent-dev)

---

Top Contributors

[![iridescent-dev](https://avatars.githubusercontent.com/u/25682686?v=4)](https://github.com/iridescent-dev "iridescent-dev (25 commits)")[![calvinrw](https://avatars.githubusercontent.com/u/687129?v=4)](https://github.com/calvinrw "calvinrw (2 commits)")[![theWituch](https://avatars.githubusercontent.com/u/5298208?v=4)](https://github.com/theWituch "theWituch (1 commits)")

---

Tags

picopicocmspicocms-pluginpicopicocmspicocms-pluginiridescentpico-toc-plugin

### Embed Badge

![Health badge](/badges/iridescent-dev-pico-toc-plugin/health.svg)

```
[![Health](https://phpackages.com/badges/iridescent-dev-pico-toc-plugin/health.svg)](https://phpackages.com/packages/iridescent-dev-pico-toc-plugin)
```

###  Alternatives

[picocms/pico

Pico is a flat file CMS, this means there is no administration backend and database to deal with. You simply create .md files in the "content" folder and that becomes a page.

3.9k37.8k11](/packages/picocms-pico)[picocms/pico-composer

Pico is a flat file CMS, this means there is no administration backend and database to deal with. You simply create .md files in the "content" folder and that becomes a page.

2020.6k](/packages/picocms-pico-composer)[picocms/pico-theme

This is Pico's official default theme. Pico is a stupidly simple, blazing fast, flat file CMS.

1232.2k2](/packages/picocms-pico-theme)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)