Nocterra

Manual - Blog Articles

Automatic Table of Contents (TOC)

In this chapter

About

Since: Nocterra 0.99.5

Nocterra can generate one or more Tables of Contents for an article based on the headings present in the article body. A TOC can be inserted automatically at a configured location, and additional per-section TOCs can be inserted inline from within the article text.

What a TOC does

A generated TOC:

collects eligible headings from the article body,
creates a nested list of links to those headings,
and injects anchor identifiers into the headings that are referenced by at least one TOC.

Headings marked with toc-ignore are excluded from TOC generation and do not appear in the TOC.

Configuration sources and precedence

TOC settings can come from:

Article header key/value pairs (toc.* keys in the article header).
Article settings (site configuration per language).
Per category settings (site configuration per category and language).
Arguments provided in the article text for %toc% (apply only to that TOC expansion).

Precedence is:

TOC placeholder arguments override the article header, per category, and site’s article settings for that specific TOC placeholder instance.
Article header values override per category and site article settings.
Per category settings apply when the article did not specify a value.
Site article settings apply when the article’s category did not specify a value.

Localized values (such as the TOC title) are evaluated per language.

Site configuration keys and defaults

In site.php you can define site-wide settings per language under {blog.article.<lang_code>. You can optionally override these settings per category and language under {blog.categories.<category_name>.<lang_code>}.

Setting	Description	Default
article_toc_location	Automatic TOC placement	`FALSE`
article_toc_minLevel	Minimum heading level	`{blog.topHeaderLevel}+2`
article_toc_maxLevel	Maximum heading level	`{blog.topHeaderLevel}+2`
article_toc_subordinate	Keep subordinate clauses	`FALSE`
article_toc_quote	Keep quoted segments	`FALSE`
article_toc_tail	Keep tail clauses	`FALSE`
article_toc_trailing	Keep trailing separators	`FALSE`
article_toc_stop	Append stop character	`FALSE`
article_toc_title	Default TOC title	`''`
article_toc_titleLevel	TOC title heading level	`{blog.topHeaderLevel}+2`

The TOC feature is optional and requires no configuration to function correctly. If you do not configure anything, no article will get an automatically inserted TOC. Authors can still generate a TOC on demand using the %toc% placeholder.

The examples below show two common configurations. They intentionally include only the keys that matter for the scenario; any omitted keys simply use Nocterra’s built-in defaults.

Example — Site article settings (English + French)


			$blog = array(
				...
				'article' => array(
					'en' => array(
						'article_toc_title'	=> 'On this page',
					),
					'fr' => array(
						'article_toc_title'	=> 'Sur cette page',
					),
				),
				...
			);

In this configuration, automatic TOC insertion remains disabled (article_toc_location is not enabled), so articles never receive a TOC unless an author explicitly inserts one in the article text. Authors can place a TOC where desired using %toc% or %toc:Title% (override the title for that one TOC instance). When %toc% is used without arguments, Nocterra applies the site’s default heading range and the configured localized TOC title; The default heading range follows the site’s header policy and is derived internally.

Example — Per category override (English)


			$blog = array(
				...
				'article' => array(
					'en' => array(
						'article_toc_title'		=> 'On this page',
					),
				...
				'categories' => array(
					'Projects' => array(
						'en' => array(
							'article_toc_title'		=> 'In this article',
							'article_toc_maxLevel'	=> 5,
						),
					),
				),
				...
			);

This per category override, changes the defaults applied when authors insert a TOC placeholder in articles published under that category. Instead of using the site-wide TOC title, the category provides its own title, and it expands the default heading range to include one additional level (for example, including both <H4> and <H5> rather than only <H4>). Automatic TOC insertion remains disabled, so authors still control where TOCs appear by placing %toc% (or %toc:Title%) within the article text.

Excluding headings: `toc-ignore` attribute

A heading can be excluded from TOC generation by adding the boolean attribute toc-ignore:


			<H4 toc-ignore>Internal notes</H4>

This attribute is used during generation and should not be relied on for styling.

Inline TOC insertion in article text

An author can insert one or more additional TOCs directly in the article body using the inline TOC placeholder.

The inline TOC placeholder supports an optional argument list:


			%toc[:[[titleLevel,]title,][minLevel,maxLevel]]%

Examples:

%toc%: use configured settings
%toc:On this page%: sets the TOC title
%toc:4,In this section%: sets the TOC title level and title
%toc:5,6%: generate a TOC for heading levels 5–6
%toc:4,Section overview,5,6%: set titleLevel=4, set the title, and generate for levels 5–6

Notes:

text (the title) is never treated as a number; it may contain digits, but it cannot be only digits.
minLevel,maxLevel are optional as a pair.

Automatic TOC insertion: `toc.location`

`toc.location`
Description:	The `toc.location` setting controls whether a TOC is inserted automatically, and where it is inserted.
Article header key:	`toc.location`
Site articles key:	`article_toc_location`
Site year / category / tag / author key:	Not supported.
Per category key:	`article_toc_location`
Per tag / author key:	Not supported.
Default:	`FALSE` (disabled)
Value:	Enumeration — supported values: `post_top` before the article/post output `body_top` at the start of the article body `body_bottom` at the end of the article body `post_bottom` after the article/post output If `toc.location` is not set (or is invalid), no automatic TOC is inserted.

Heading selection: `toc.minLevel` and `toc.maxLevel`

These settings control which heading levels are eligible for inclusion. Only headings with minLevel <= Hn <= maxLevel can become TOC entries.

`toc.minLevel`
Description:	The minimum heading level that can become a TOC entry.
Article header key:	`toc.minLevel`
Site articles key:	`article_toc_minLevel`
Site year / category / tag / author key:	Not supported.
Per category key:	`article_toc_minLevel`
Per tag / author key:	Not supported.
Default:	`{blog.topHeaderLevel}+2`
Value:	Numeric — `1` to `6`

`toc.maxLevel`
Description:	The maximum heading level that can become a TOC entry.
Article header key:	`toc.maxLevel`
Site articles key:	`article_toc_maxLevel`
Site year / category / tag / author key:	Not supported.
Per category key:	`article_toc_maxLevel`
Per tag / author key:	Not supported.
Default:	`{blog.topHeaderLevel}+2`
Value:	Numeric — `1` to `6`

TOC title: `toc.title` and `toc.titleLevel`

A TOC can optionally display a title above the list.

toc.title:<lang> — localized title string (may include HTML)
toc.titleLevel — heading level used for the TOC title output

`toc.title`
Description:	Optional TOC title shown above the list. The title may include HTML.
Article header key:	`toc.title:<lang>`
Site articles key:	`article_toc_title`
Site year / category / tag / author key:	Not supported.
Per category key:	`article_toc_title`
Per tag / author key:	Not supported.
Default:	`''` (empty string; no title)
Value:	String (may include HTML). Empty string disables the title.

`toc.titleLevel`
Description:	Heading level used to render the TOC title.
Article header key:	`toc.titleLevel`
Site articles key:	`article_toc_titleLevel`
Site year / category / tag / author key:	Not supported.
Per category key:	`article_toc_titleLevel`
Per tag / author key:	Not supported.
Default:	`{blog.topHeaderLevel}+2`
Value:	Numeric — `1` to `6`

When a TOC title is provided, the TOC is exposed to assistive technology as a labeled navigation landmark, making it easier to discover and jump to.

TOC label shaping settings

For each included heading, Nocterra derives the TOC label from the heading’s text content and optionally simplifies it. The following inclusive toggles control which constructs are kept.

Example headings:


			<H4>Home networking (quick start): VLAN trunking basics</H4>
			<H4>Budgeting basics (2026) — “needs vs wants” explained</H4>
			<H4>Cooking risotto (step-by-step) [no fancy tools]</H4>
			<H4>Troubleshooting “Why does this happen?” (FAQ)</H4>
			<H4>What’s next:</H4>
			<H4>A quick note,</H4>
			<H4>Just a heading.</H4>
			<H4>Great results!</H4>
			<H4>スタジオ照明「三点照明」入門（基本）</H4>
			<H4>أساسيات الإضاءة «مبتدئين»، ثم شرح: أمثلة سريعة</H4>
			<H4>पोर्ट्रेट लाइटिंग “मूल बातें” (शुरुआती)</H4>

Example label shaping toggles to simplify TOC labels:


			toc.subordinate = TRUE
			toc.quote       = FALSE
			toc.tail        = FALSE
			toc.trailing    = FALSE
			toc.stop        = .

Resulting TOC labels:

Home networking (quick start).
Budgeting basics (2026).
Cooking risotto (step-by-step) [no fancy tools].
Troubleshooting (FAQ).
What’s next.
A quick note.
Just a heading.
Great results!
スタジオ照明入門（基本）.
أساسيات الإضاءة ثم شرح.
पोर्ट्रेट लाइटिंग (शुरुआती).

Example label shaping toggles to simplify TOC labels:


			toc.subordinate = FALSE
			toc.quote       = TRUE
			toc.tail        = FALSE
			toc.trailing    = TRUE
			toc.stop        = .

Resulting TOC labels:

Home networking.
Budgeting basics.
Cooking risotto.
Troubleshooting “Why does this happen?”
What’s next.
A quick note.
Just a heading.
Great results!
スタジオ照明「三点照明」入門（基本）.
أساسيات الإضاءة «مبتدئين»، ثم شرح.
पोर्ट्रेट लाइटिंग “मूल बातें” (शुरुआती).

Notes:

Subordinate stripping removes bracketed clauses like (...), and equivalent international bracket forms.
Quote stripping removes quoted segments like “...”, «... », and 「...」.
Tail stripping removes everything from the first recognized separator (such as :, ,, ،, or ؛) onward.
Trailing stripping removes a trailing separator if one remains at end-of-label (including ، and ؛).
The stop character is appended only when appropriate (to avoid outputs such as Why?.).

`toc.subordinate`
Description:	Controls subordinate clauses in brackets/parentheses (including international bracket forms).
Article header key:	`toc.subordinate`
Site articles key:	`article_toc_subordinate`
Site year / category / tag / author key:	Not supported.
Per category key:	`article_toc_subordinate`
Per tag / author key:	Not supported.
Default:	`FALSE`
Value:	Boolean — `true` keeps subordinate clauses; `false` removes them.

`toc.quote`
Description:	Controls quoted segments (including international quote forms such as «…», “…” and CJK quotes).
Article header key:	`toc.quote`
Site articles key:	`article_toc_quote`
Site year / category / tag / author key:	Not supported.
Per category key:	`article_toc_quote`
Per tag / author key:	Not supported.
Default:	`FALSE`
Value:	Boolean — `true` keeps quoted segments; `false` removes them.

`toc.tail`
Description:	Controls tail clauses following separators such as commas/colons/semicolons and dash punctuation used as a clause separator.
Article header key:	`toc.tail`
Site articles key:	`article_toc_tail`
Site year / category / tag / author key:	Not supported.
Per category key:	`article_toc_tail`
Per tag / author key:	Not supported.
Default:	`FALSE`
Value:	Boolean — `true` keeps tail clauses; `false` removes tail clauses from the first recognized separator onward.

`toc.trailing`
Description:	Controls cleanup of trailing separator punctuation at the end of the TOC label (comma/colon/semicolon and international variants, including Arabic `،` and `؛`).
Article header key:	`toc.trailing`
Site articles key:	`article_toc_trailing`
Site year / category / tag / author key:	Not supported.
Per category key:	`article_toc_trailing`
Per tag / author key:	Not supported.
Default:	`FALSE`
Value:	Boolean — `true` keeps trailing separators; `false` strips trailing separators at end-of-label.

After optional stripping, whitespace is normalized (trimmed; repeated whitespace collapsed).

Stop character: `toc.stop`

The toc.stop setting controls optional appending of a stop character to the TOC label, to make TOC labels consistent.

`toc.stop`
Description:	Controls optional appending of a stop character to the TOC label, to make labels consistent.
Article header key:	`toc.stop`
Site articles key:	`article_toc_stop`
Site year / category / tag / author key:	Not supported.
Per category key:	`article_toc_stop`
Per tag / author key:	Not supported.
Default:	`FALSE` (no stop appended)
Value:	Boolean or string: `FALSE`/`no`/`off`/`0` disables stop appending. `TRUE`/`yes`/`on`/`1` enables stop appending with default `'.'`. Any other string value uses that string as the stop character (e.g., `'.'`, `'!'`, `'…'`, `'。'`).

The stop character is appended only when the label ends in a word character (Unicode-aware), optionally followed by closing brackets/quotes. This avoids producing outputs such as Why?..

Examples:

Heading: In this paragraph:
with toc.trailing=false and toc.stop='.' → In this paragraph.
Heading: Why?
stop is not appended → Why?

Anchor injection behavior

Nocterra injects anchor identifiers into headings so TOC links can target them.

The system tracks the minimum and maximum heading level that is referenced by any generated TOC (including inline TOCs). After TOC generation, anchors are injected into headings whose level falls within that used range.

This allows mixed usage such as:

a global TOC at <H4>, plus
additional per-section TOCs for <H5>–<H6>.

while ensuring only headings that are actually referenced by a TOC receive anchors.

Examples

This chapter provides practical examples of how TOC settings (defaults, site article settings, per category overrides, and article header keys) can be combined with inline TOC placeholders to achieve common layouts.

Example 1 — Enable a single TOC at the top of every article (site-wide)

For all articles in a language, automatically insert one TOC at the start of the article body using the default heading level policy. With the settings shown below, every article gets a TOC at the top of the article body, linking to headings at the default level (typically <H4> if the site uses <H2> as top header level).

In site.php set:


			$blog = array(
				...
				'article' => array(
					'en' => array(
						'article_toc_location'		=> 'body_top',
						'article_toc_title'			=> 'On this page',
					),
					'nl' => array(
						'article_toc_location'		=> 'body_top',
						'article_toc_title'			=> 'Op deze pagina',
					),
					'fa' => array(
						'article_toc_location'		=> 'body_top',
						'article_toc_title'			=> 'در این صفحه',
					),
				),
				...
			);

Example 2 — Category override: different title and different default levels

For a specific category, insert the TOC at the top and include deeper headings by default (e.g., include <H4> and <H5>). Use a category-specific TOC title. With the below settings, articles in the Projects category get a TOC with a different title and a deeper default range, without affecting other categories.

In site.php set:


			$blog = array(
				...
				'article' => array(
					'en' => array(
						'article_toc_location'		=> 'body_top',
						'article_toc_title'			=> 'On this page',
					),
					'ja' => array(
						'article_toc_location'		=> 'body_top',
						'article_toc_title'			=> 'このページの内容',
					),
				),
				...
				'categories' => array(
					'Projects' => array(
						'en' => array(
							'article_toc_maxLevel'	=> 5,
							'article_toc_title'		=> 'In this article',
						),
						'ja' => array(
							'article_toc_maxLevel'	=> 5,
							'article_toc_title'		=> 'この記事の内容',
						),
					),
				),
				...
			);

Example 3 — Article header overrides: disable automatic TOC for one article

The site normally inserts an automatic TOC, but a specific article should not have an automatically inserted TOC.

With the key/value pair set in the article header, no automatic TOC is inserted for that article. Inline TOCs may still be used via %toc% placeholders.

Note: Use values highlighted by your editor, or you find convenient, for boolean “off”. If you standardize on FALSE or off, document that convention site-wide for consistency.

In site.php set:


			$blog = array(
				...
				'article' => array(
					'nl' => array(
						'article_toc_location'		=> 'body_top',
						'article_toc_title'			=> 'In dit artikel',
					),
					'fy' => array(
						'article_toc_location'		=> 'body_top',
						'article_toc_title'			=> 'Yn dit artikel',
					),
				),
				...
			);

In the article file add the header key/value:


			toc.location = off

Example 4 — A single article uses an automatic TOC

On a site that otherwise does not use automatic TOCs, a specific article may still include a TOC. In the article file snippet below, an automatically generated TOC is inserted after an introductory paragraph, with the TOC title and included heading levels configured in the article header.

In the article file:


			author			= Emre
			published		= 2024-11-12
			category		= Fotoğrafçılık
			tags			= Aydınlatma, Stüdyo, Portre, Temel bilgiler, Ekipman, Pratik ipuçları
			keywords		= fotoğraf aydınlatma, ışık yönü, yumuşak ışık, sert ışık, üç nokta ışık, portre ışıklandırma, stüdyo ışığı, softbox, reflektör, ışık ölçümü, pozlama, ISO diyafram enstantane, gölge kontrolü, ışık kalitesi
			title			= Fotoğraf Aydınlatma Rehberi: Işığı Kontrol Etmeyi Öğrenin
			description		= Başlangıç seviyesinde fotoğraf aydınlatma: ışığın yönü ve kalitesi, sert/yumuşak ışık, temel ekipman ve pratik portre ışıklandırma adımları.
			toc.title		= Bu yazıda
			toc.maxLevel	= 5
			toc.quote		= TRUE
			toc.stop		= TRUE
			
			[body]
			
			<P>Bu yazı, hobi fotoğrafçılığı yapanlar için temel bir <STRONG>aydınlatma</STRONG> eğitimidir. Işığın yönünü, kalitesini ve gölgeleri nasıl kontrol edeceğinizi adım adım ele alacağız. Evde basit ekipmanla başlayıp, stüdyo kurulumlarına kadar uzanan pratik örnekler bulacaksınız.</P>
			
			%toc%
			
			<H4>Işığı anlamak: yön, kalite ve kontrast</H4>
			
			<P>...</P>

Nocterra

Manual - Blog Articles

Automatic Table of Contents (TOC)

In this chapter

About

What a TOC does

Configuration sources and precedence

Site configuration keys and defaults

Example — Site article settings (English + French)

Example — Per category override (English)

Excluding headings: `toc-ignore` attribute

Inline TOC insertion in article text

Automatic TOC insertion: `toc.location`

Heading selection: `toc.minLevel` and `toc.maxLevel`

TOC title: `toc.title` and `toc.titleLevel`

TOC label shaping settings

Stop character: `toc.stop`

Heading: `In this paragraph:`

Heading: `Why?`

Anchor injection behavior

Examples

Example 1 — Enable a single TOC at the top of every article (site-wide)

Example 2 — Category override: different title and different default levels

Example 3 — Article header overrides: disable automatic TOC for one article

Example 4 — A single article uses an automatic TOC

Nocterra

Manual - Blog Articles

Automatic Table of Contents (TOC)

In this chapter

What a TOC does

Example — Site article settings (English + French)

Example — Per category override (English)

Heading: In this paragraph:

Heading: Why?

Example 1 — Enable a single TOC at the top of every article (site-wide)

Example 2 — Category override: different title and different default levels

Example 3 — Article header overrides: disable automatic TOC for one article

Example 4 — A single article uses an automatic TOC

Heading: `In this paragraph:`

Heading: `Why?`