iridescent-dev/pico-toc-plugin

A Table Of Contents plugin for Pico CMS.

Maintainers

Details

github.com/iridescent-dev/pico-toc-plugin

Homepage

Source

Issues

Documentation

Installs: 76

Dependents: 0

Suggesters: 0

Security: 0

Stars: 6

Watchers: 3

Forks: 4

Open Issues: 10

Type:pico-plugin

2.1 2022-01-18 17:13 UTC

Requires

  • php: >=7.0

Requires (Dev)

MIT 79fed34f87efbcb8b93e7672850af9497e305801

  • Véronique Seguela <veronique.woop@iridescent.dev>
  • Contributors

picocmspicopicocms-pluginiridescentpico-toc-plugin

This package is auto-updated.

Last update: 2024-04-18 22:24:16 UTC

README

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

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

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

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

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>

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

Template variables defined for Twig

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

Example

The index.md 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 `<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.

Screenshot

Screenshot.png

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.