{toc}

A table of contents of the page from its own rendered headings, nested and linked - filled in once the page has rendered.

Text and formatting Single tags

Syntax 

{toc}
{toc levels='2-4', title='On this page', list='ul'}

Options

levels
The heading levels listed - a list or a range, '2,3' by default, '2-4'.
title
The label above the list, Contents by default; '' for none.
list
ol (numbered, the default) or ul.

Description

{toc} writes a table of contents of the page it stands in, from the page's own rendered headings - <h2> and <h3> by default - as a <nav> with nested, linked lists. Like {stack}, the tag writes a marker that is filled in once the whole page has rendered, so the headings below it are listed too, including the ones a loop, a snippet or a {markdown} produced.

A heading without an id gets one to link to: the slug of its text, with -2, -3 behind a repeat, never an id the page already has. A heading with an id keeps it. A level one deeper nests one list deeper, never more than one step in, so a page that skips from <h2> to <h4> still gives a sound list. The title is a paragraph rather than a heading, so the contents never list themselves. Without a heading of the chosen levels, the tag writes nothing.

The marker is filled in when the request's page ends and also when a {page} pass ends for a page it renders, so a {toc} in such a page lists the headings of that page alone - which is how the examples here list their own headings and not those of this page. Colours are --pad-toc-* custom properties with light-dark() defaults. Levels outside 1 to 6 and a list other than ol or ul are strict errors.

Examples

Contents above an article

The contents stand above the headings they list; every heading gets an id to link to.

Templateexamples/toc/1-article.pad 
<article style="max-width:40em">
  {toc title='In this article'}
  <h2>Choosing the beans</h2>
  <p>Buy whole beans roasted in the last few weeks.</p>
  <h3>Light or dark roast</h3>
  <p>A light roast keeps the fruit; a dark roast trades it for body.</p>
  <h2>Grinding</h2>
  <p>Grind just before brewing, coarse for a press and fine for espresso.</p>
  <h2>Brewing</h2>
  <h3>Pour-over</h3>
  <p>Bloom the grounds for thirty seconds, then pour slowly.</p>
  <h3>French press</h3>
  <p>Steep four minutes and press gently.</p>
</article>
Resultopen alone

Choosing the beans

Buy whole beans roasted in the last few weeks.

Light or dark roast

A light roast keeps the fruit; a dark roast trades it for body.

Grinding

Grind just before brewing, coarse for a press and fine for espresso.

Brewing

Pour-over

Bloom the grounds for thirty seconds, then pour slowly.

French press

Steep four minutes and press gently.

Three levels as bullets

levels= picks the levels, list= the kind of list; a heading with its own id keeps it.

Templateexamples/toc/2-levels.pad 
{toc levels='2-4', list='ul', title='On this page'}
<h2 id="install">Installation</h2>
<h3>Requirements</h3>
<h4>Extensions</h4>
<h3>First run</h3>
<h2>Configuration</h2>
Resultopen alone

Installation

Requirements

Extensions

First run

Configuration

See also

  • {stack} Prints everything pushed to a named stack, from above or below it in the page.
  • {markdown} Renders its content, or the value of its parameter, as Markdown and writes the HTML.
  • {page} Renders another page of the application - its PHP and its template - in place of the tag.