Nocterra CMS

Handleiding - Blog Articles

Automatic Table of Contents (TOC)

In dit hoofdstuk

Over

Sinds: Nocterra 0.99.5

Terminologie: Technische Nocterra-termen blijven in deze Nederlandse handleiding onvertaald, zodat ze één-op-één terug te vinden zijn in de API, configuratie en article headers.

Nocterra kan één of meer Tables of Contents voor een article genereren op basis van de headings die aanwezig zijn in de article body. Een TOC kan automatisch op een geconfigureerde locatie worden ingevoegd, en aanvullende per-section TOCs kunnen inline vanuit de article text worden ingevoegd.

Wat een TOC doet

Een gegenereerde TOC:

verzamelt geschikte headings uit de article body,
maakt een geneste lijst met links naar die headings,
en voegt anchor identifiers toe aan de headings waarnaar door ten minste één TOC wordt verwezen.

Headings die zijn gemarkeerd met toc-ignore worden uitgesloten van TOC generation en verschijnen niet in de TOC.

Configuratiebronnen en prioriteit

TOC settings kunnen afkomstig zijn uit:

Article header key/value pairs (toc.* keys in de article header).
Article settings (site configuration per language).
Per category settings (site configuration per category en language).
Argumenten die in de article text worden meegegeven aan %toc% (gelden alleen voor die TOC expansion).

De prioriteit is:

TOC placeholder arguments overschrijven de article header, per category, en site’s article settings voor die specifieke TOC placeholder instance.
Article header waarden overschrijven per category en site article settings.
Per category settings gelden wanneer de article geen waarde heeft opgegeven.
Site article settings gelden wanneer de category van de article geen waarde heeft opgegeven.

Gelokaliseerde waarden (zoals de TOC title) worden per language bepaald.

Site configuration keys en standaardwaarden

In site.php kun je site-wide settings per language definiëren onder {blog.article.<lang_code>. Je kunt deze settings desgewenst per category en language overschrijven onder {blog.categories.<category_name>.<lang_code>}.

Setting	Beschrijving	Standaard
article_toc_location	Automatische plaatsing van de TOC	`FALSE`
article_toc_minLevel	Minimaal heading level	`{blog.topHeaderLevel}+2`
article_toc_maxLevel	Maximaal heading level	`{blog.topHeaderLevel}+2`
article_toc_subordinate	Subordinate clauses behouden	`FALSE`
article_toc_quote	Quoted segments behouden	`FALSE`
article_toc_tail	Tail clauses behouden	`FALSE`
article_toc_trailing	Trailing separators behouden	`FALSE`
article_toc_stop	Stop character toevoegen	`FALSE`
article_toc_title	Standaard TOC title	`''`
article_toc_titleLevel	Heading level van de TOC title	`{blog.topHeaderLevel}+2`

De TOC feature is optioneel en vereist geen configuratie om correct te werken. Als niets wordt geconfigureerd, krijgt geen enkele article een automatisch ingevoegde TOC. Authors kunnen nog steeds op verzoek een TOC genereren met de %toc% placeholder.

De voorbeelden hieronder tonen twee veelgebruikte configuraties. Ze bevatten bewust alleen de keys die voor het scenario van belang zijn; weggelaten keys gebruiken gewoon de ingebouwde standaardwaarden van Nocterra.

Voorbeeld — Site article settings (Engels + Frans)

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

In deze configuratie blijft automatic TOC insertion uitgeschakeld (article_toc_location is niet ingeschakeld), waardoor articles nooit een TOC krijgen tenzij een author er expliciet een invoegt in de article text. Authors kunnen een TOC op de gewenste plaats invoegen met %toc% of %toc:Title% (overschrijft de title voor die ene TOC instance). Wanneer %toc% zonder argumenten wordt gebruikt, past Nocterra de standaard heading range van de site en de geconfigureerde gelokaliseerde TOC title toe; de standaard heading range volgt de header policy van de site en wordt intern afgeleid.

Voorbeeld — Per category override (Engels)

$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,
				),
			),
		),
		...
	);

Deze per category override wijzigt de standaardwaarden die worden toegepast wanneer authors een TOC placeholder invoegen in articles die onder die category zijn gepubliceerd. In plaats van de site-wide TOC title gebruikt de category zijn eigen title en breidt deze de standaard heading range uit met één extra level (bijvoorbeeld zowel <H4> als <H5> in plaats van alleen <H4>). Automatic TOC insertion blijft uitgeschakeld, zodat authors zelf bepalen waar TOCs verschijnen door %toc% (of %toc:Title%) in de article text.

Headings uitsluiten: `toc-ignore` attribute

Een heading kan worden uitgesloten van TOC generation door het boolean attribute toc-ignore:

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

Dit attribute wordt tijdens generation gebruikt en moet niet worden gebruikt als basis voor styling.

Inline TOC insertion in article text

Een author kan één of meer aanvullende TOCs rechtstreeks in de article body invoegen met de inline TOC placeholder.

De inline TOC placeholder ondersteunt een optionele argument list:

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

Voorbeelden:

%toc%: gebruik de geconfigureerde settings
%toc:On this page%: stelt de TOC title in
%toc:4,In this section%: stelt de TOC title level en title in
%toc:5,6%: genereer een TOC voor heading levels 5–6
%toc:4,Section overview,5,6%: stel titleLevel=4, stel de title, en genereer voor levels 5–6

Opmerkingen:

text (de title) wordt nooit als getal behandeld; deze mag cijfers bevatten, maar mag niet uitsluitend uit cijfers bestaan.
minLevel,maxLevel zijn als paar optioneel.

Automatic TOC insertion: `toc.location`

`toc.location`
Beschrijving:	De `toc.location` setting bepaalt of een TOC automatisch wordt ingevoegd en waar deze wordt ingevoegd.
Article header key:	`toc.location`
Site articles key:	`article_toc_location`
Site year / category / tag / author key:	Niet ondersteund.
Per category key:	`article_toc_location`
Per tag / author key:	Niet ondersteund.
Standaard:	`FALSE` (uitgeschakeld)
Waarde:	Enumeratie — ondersteunde waarden: `post_top` vóór de article/post output `body_top` aan het begin van de article body `body_bottom` aan het einde van de article body `post_bottom` na de article/post output Als `toc.location` niet is ingesteld (of ongeldig is), wordt geen automatische TOC ingevoegd.

Heading-selectie: `toc.minLevel` en `toc.maxLevel`

Deze settings bepalen welke heading levels voor opname in aanmerking komen. Alleen headings met minLevel <= Hn <= maxLevel kunnen TOC entries worden.

`toc.minLevel`
Beschrijving:	Het minimale heading level dat een TOC entry kan worden.
Article header key:	`toc.minLevel`
Site articles key:	`article_toc_minLevel`
Site year / category / tag / author key:	Niet ondersteund.
Per category key:	`article_toc_minLevel`
Per tag / author key:	Niet ondersteund.
Standaard:	`{blog.topHeaderLevel}+2`
Waarde:	Numeriek — `1` tot `6`

`toc.maxLevel`
Beschrijving:	Het maximale heading level dat een TOC entry kan worden.
Article header key:	`toc.maxLevel`
Site articles key:	`article_toc_maxLevel`
Site year / category / tag / author key:	Niet ondersteund.
Per category key:	`article_toc_maxLevel`
Per tag / author key:	Niet ondersteund.
Standaard:	`{blog.topHeaderLevel}+2`
Waarde:	Numeriek — `1` tot `6`

TOC title: `toc.title` en `toc.titleLevel`

Een TOC kan optioneel een title boven de lijst weergeven.

toc.title:<lang> — gelokaliseerde title string (mag HTML bevatten)
toc.titleLevel — heading level gebruikt voor de output van de TOC title

`toc.title`
Beschrijving:	Optionele TOC title die boven de lijst wordt weergegeven. De title mag HTML bevatten.
Article header key:	`toc.title:<lang>`
Site articles key:	`article_toc_title`
Site year / category / tag / author key:	Niet ondersteund.
Per category key:	`article_toc_title`
Per tag / author key:	Niet ondersteund.
Standaard:	`''` (lege string; geen title)
Waarde:	String (mag HTML bevatten). Een lege string schakelt de title uit.

`toc.titleLevel`
Beschrijving:	Heading level dat wordt gebruikt om de TOC title te renderen.
Article header key:	`toc.titleLevel`
Site articles key:	`article_toc_titleLevel`
Site year / category / tag / author key:	Niet ondersteund.
Per category key:	`article_toc_titleLevel`
Per tag / author key:	Niet ondersteund.
Standaard:	`{blog.topHeaderLevel}+2`
Waarde:	Numeriek — `1` tot `6`

Wanneer een TOC title is opgegeven, wordt de TOC aan assistive technology aangeboden als een gelabeld navigation landmark, zodat gebruikers deze eenvoudiger kunnen vinden en er direct naartoe kunnen navigeren.

TOC label shaping settings

Voor elke opgenomen heading leidt Nocterra de TOC label af uit de text content van de heading en vereenvoudigt deze desgewenst. De volgende inclusieve toggles bepalen welke constructies behouden blijven.

Voorbeeld 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>

Voorbeeld van label shaping toggles om TOC labels te vereenvoudigen:

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

Resulterende 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!
スタジオ照明入門（基本）.
أساسيات الإضاءة ثم شرح.
पोर्ट्रेट लाइटिंग (शुरुआती).

Voorbeeld van label shaping toggles om TOC labels te vereenvoudigen:

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

Resulterende TOC labels:

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

Opmerkingen:

Subordinate stripping verwijdert clauses tussen brackets zoals (...), en equivalente internationale bracket-vormen.
Quote stripping verwijdert quoted segments zoals “...”, «... », en 「...」.
Tail stripping verwijdert alles vanaf de eerste herkende separator (zoals :, ,, ،, of ؛) en verder.
Trailing stripping verwijdert een trailing separator als die aan het einde van het label overblijft (inclusief ، en ؛).
Het stop character wordt alleen toegevoegd wanneer dat passend is (om output zoals Why?. te voorkomen).

`toc.subordinate`
Beschrijving:	Bepaalt het gedrag voor subordinate clauses tussen brackets/parentheses (inclusief internationale bracket-vormen).
Article header key:	`toc.subordinate`
Site articles key:	`article_toc_subordinate`
Site year / category / tag / author key:	Niet ondersteund.
Per category key:	`article_toc_subordinate`
Per tag / author key:	Niet ondersteund.
Standaard:	`FALSE`
Waarde:	Boolean — `true` behoudt subordinate clauses; `false` verwijdert ze.

`toc.quote`
Beschrijving:	Bepaalt het gedrag voor quoted segments (inclusief internationale quote-vormen zoals «…», “…” en CJK quotes).
Article header key:	`toc.quote`
Site articles key:	`article_toc_quote`
Site year / category / tag / author key:	Niet ondersteund.
Per category key:	`article_toc_quote`
Per tag / author key:	Niet ondersteund.
Standaard:	`FALSE`
Waarde:	Boolean — `true` behoudt quoted segments; `false` verwijdert ze.

`toc.tail`
Beschrijving:	Bepaalt het gedrag voor tail clauses na separators zoals komma's/dubbele punten/puntkomma's en dash-punctuation die als clause separator wordt gebruikt.
Article header key:	`toc.tail`
Site articles key:	`article_toc_tail`
Site year / category / tag / author key:	Niet ondersteund.
Per category key:	`article_toc_tail`
Per tag / author key:	Niet ondersteund.
Standaard:	`FALSE`
Waarde:	Boolean — `true` behoudt tail clauses; `false` verwijdert tail clauses vanaf de eerste herkende separator.

`toc.trailing`
Beschrijving:	Bepaalt het opschonen van trailing separator punctuation aan het einde van de TOC label (komma/dubbele punt/puntkomma en internationale varianten, inclusief Arabisch `،` en `؛`).
Article header key:	`toc.trailing`
Site articles key:	`article_toc_trailing`
Site year / category / tag / author key:	Niet ondersteund.
Per category key:	`article_toc_trailing`
Per tag / author key:	Niet ondersteund.
Standaard:	`FALSE`
Waarde:	Boolean — `true` behoudt trailing separators; `false` verwijdert trailing separators aan het einde van het label.

Na eventuele stripping wordt whitespace genormaliseerd (getrimd; herhaalde whitespace wordt samengevoegd).

Stop character: `toc.stop`

De toc.stop setting bepaalt het optioneel toevoegen van een stop character aan de TOC label, om TOC labels consistent te maken.

`toc.stop`
Beschrijving:	Bepaalt het optioneel toevoegen van een stop character aan de TOC label, om labels consistent te maken.
Article header key:	`toc.stop`
Site articles key:	`article_toc_stop`
Site year / category / tag / author key:	Niet ondersteund.
Per category key:	`article_toc_stop`
Per tag / author key:	Niet ondersteund.
Standaard:	`FALSE` (geen stop character toegevoegd)
Waarde:	Boolean of string: `FALSE`/`no`/`off`/`0` schakelt het toevoegen van een stop character uit. `TRUE`/`yes`/`on`/`1` schakelt het toevoegen van een stop character in met standaardwaarde `'.'`. Elke andere stringwaarde gebruikt die string als stop character (bijvoorbeeld `'.'`, `'!'`, `'…'`, `'。'`).

Het stop character wordt alleen toegevoegd wanneer het label eindigt op een word character (Unicode-aware), eventueel gevolgd door afsluitende brackets/quotes. Dit voorkomt output zoals Why?..

Voorbeelden:

Heading: In this paragraph:
met toc.trailing=false en toc.stop='.' → In this paragraph.
Heading: Why?
stop character wordt niet toegevoegd → Why?

Gedrag bij het invoegen van anchors

Nocterra voegt anchor identifiers toe aan headings zodat TOC links ernaar kunnen verwijzen.

Het systeem houdt het minimale en maximale heading level bij waarnaar door een gegenereerde TOC wordt verwezen (inclusief inline TOCs). Na TOC generation worden anchors toegevoegd aan headings waarvan het level binnen dat gebruikte bereik valt.

Dit maakt gemengd gebruik mogelijk, zoals:

een globale TOC op <H4>, plus
aanvullende per-section TOCs voor <H5>–<H6>.

Zo krijgen alleen headings waarnaar daadwerkelijk door een TOC wordt verwezen anchors.

Voorbeelden

Dit hoofdstuk geeft praktische voorbeelden van hoe TOC settings (defaults, site article settings, per category overrides en article header keys) kunnen worden gecombineerd met inline TOC placeholders om veelgebruikte layouts te realiseren.

Voorbeeld 1 — Eén TOC bovenaan iedere article inschakelen (site-wide)

Voeg voor alle articles in een language automatisch één TOC in aan het begin van de article body met de standaard heading level policy. Met de settings hieronder krijgt iedere article een TOC bovenaan de article body, met links naar headings op het standaardlevel (doorgaans <H4> als de site <H2> als top header level gebruikt).

Stel in site.php in:

$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'			=> 'در این صفحه',
			),
		),
		...
	);

Voorbeeld 2 — Category override: andere title en andere standaardlevels

Voeg voor een specifieke category de TOC bovenaan in en neem standaard diepere headings op (bijvoorbeeld <H4> en <H5>). Gebruik een category-specifieke TOC title. Met de settings hieronder krijgen articles in de Projects category een TOC met een andere title en een dieper standaardbereik, zonder andere categories te beïnvloeden.

Stel in site.php in:

	$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'		=> 'この記事の内容',
				),
			),
		),
		...
	);

Voorbeeld 3 — Article header overrides: automatische TOC uitschakelen voor één article

De site voegt normaal automatisch een TOC in, maar een specifieke article moet geen automatisch ingevoegde TOC krijgen.

Met het key/value pair dat in de article header is ingesteld, wordt voor die article geen automatische TOC ingevoegd. Inline TOCs kunnen nog steeds worden gebruikt via %toc% placeholders.

Opmerking: Gebruik voor boolean “off” de waarden die je editor benadrukt of die je zelf handig vindt. Als je standaardiseert op FALSE of off, documenteer die conventie dan site-wide voor consistentie.

Stel in site.php in:

$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',
			),
		),
		...
	);

Voeg in de article file de volgende header key/value toe:

toc.location = off

Voorbeeld 4 — Eén article gebruikt een automatische TOC

Op een site die verder geen automatische TOCs gebruikt, kan een specifieke article toch een TOC bevatten. In het article file snippet hieronder wordt een automatisch gegenereerde TOC na een inleidende paragraph ingevoegd, waarbij de TOC title en de opgenomen heading levels in de article header worden geconfigureerd.

In de 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 CMS

Handleiding - Blog Articles

Automatic Table of Contents (TOC)

In dit hoofdstuk

Over

Wat een TOC doet

Configuratiebronnen en prioriteit

Site configuration keys en standaardwaarden

Voorbeeld — Site article settings (Engels + Frans)

Voorbeeld — Per category override (Engels)

Headings uitsluiten: `toc-ignore` attribute

Inline TOC insertion in article text

Automatic TOC insertion: `toc.location`

Heading-selectie: `toc.minLevel` en `toc.maxLevel`

TOC title: `toc.title` en `toc.titleLevel`

TOC label shaping settings

Stop character: `toc.stop`

Heading: `In this paragraph:`

Heading: `Why?`

Gedrag bij het invoegen van anchors

Voorbeelden

Voorbeeld 1 — Eén TOC bovenaan iedere article inschakelen (site-wide)

Voorbeeld 2 — Category override: andere title en andere standaardlevels

Voorbeeld 3 — Article header overrides: automatische TOC uitschakelen voor één article

Voorbeeld 4 — Eén article gebruikt een automatische TOC

Nocterra CMS

Handleiding - Blog Articles

Automatic Table of Contents (TOC)

In dit hoofdstuk

Wat een TOC doet

Voorbeeld — Site article settings (Engels + Frans)

Voorbeeld — Per category override (Engels)

Heading: In this paragraph:

Heading: Why?

Voorbeeld 1 — Eén TOC bovenaan iedere article inschakelen (site-wide)

Voorbeeld 2 — Category override: andere title en andere standaardlevels

Voorbeeld 3 — Article header overrides: automatische TOC uitschakelen voor één article

Voorbeeld 4 — Eén article gebruikt een automatische TOC

Heading: `In this paragraph:`

Heading: `Why?`