Twig :: toc

The toc filter is stakx's method of generating a table of contents (TOC) for any HTML.

Since

0.1.3

Usage

toc(html, id = null, class = null, hMin = 1, hMax = 6)

Parameters

  • (required) html : string

    The HTML from which to generate a TOC from

  • id : string

    The ID to assign to the generated TOC

  • class : string

    The class(es) to assign to the generated TOC

  • hMin : int

    The minimum heading to use. A heading lower than this value would be ignored

  • hMax : int

    The maximum heading to use. A heading greater than this value would be ignored

Example Usage

stakx's markdown engine does not have an equivalent of kramdown's {:toc}, for good reason. While {:toc} may be useful, it restricts users with a lack of configuration options and the placement of the generated table often cannot be put in a semantically correct location. For this reason, the same functionality is provided in stakx as a Twig filter instead.

Use correct headings

When writing your documents, be sure to use correct headings and do not use headings simple to change font size. If you're using a heading 2 (##), the next sub heading, if any, should be a heading 3 (###). Using incorrect headings will cause a broken TOC to be generated.

Given the following markdown,

# Heading 1

Lorem ipsum...

## Sub Heading 1

Toast with cheese...

## Sub Heading 2

Hello world...

In dynamic PageViews, the generated markdown is accessible through {{ this.content }} and this value is what is passed to the toc filter; as seen in the following example:

{{ this.content | toc }}

hMin Behavior

In the above markdown, if you set hMin to 2, then it'll generate a TOC with only "Sub Heading 1" and "Sub Heading 2". However, if there was another heading 1 in that markdown document and hMin were set to 2, a broken TOC would be generated; this is intended behavior and not a bug.