Nocterra CMS

Manual - Blog Articles

Definitions

In this chapter

About

Since: Nocterra 0.99.3

Nocterra supports term definitions in article files. Definitions allow an author to write a definition term like {term} in the article body and have Nocterra expand it into consistent, semantic markup (and optionally a link) during article generation.

This is useful for:

introducing key terms once (as a definition) and styling subsequent mentions consistently,
providing optional tooltips (title) and links (link),
and keeping the article text clean while still producing richly marked-up output.

Headings, paragraphs, and other text content may contain definition terms, for example:

<CODE>{term}</CODE>
<H4>Using {term} in a practical way</H4>
<A href="...">Lookup more about {term}</A> (definitions without links only)

Rule: A definition term must not be used inside an HTML element name or inside an attribute name/value. Definition terms are meant for text content only.

Writing definitions

Definitions are written in the [definitions] section of an article file. A definition starts with a non-indented line containing the definition name. The following indented lines assign keys using key = value pairs.

Minimal example:

[definitions]

Term
	type  = default
	title = A short explanation shown as a tooltip

[body]
<P>In this article we will use {Term} multiple times.</P>

Definition names are used verbatim. This means {Term} and {term} are different definition terms unless you explicitly provide a matching synonym. Case prefixes alter only the rendered text and do not change this exact lookup behavior (see Case prefixes and synonyms).

Definition keys

Within a definition, the following keys are supported:

Key	Description
type	controls the semantic markup used (see Definition types).
link	the URL used for all occurrences of the term (when linking is enabled).
link-first	optional URL used for the first occurrence only.
title	optional tooltip (`title` attribute) for all occurrences.
title-first	optional tooltip for the first occurrence only.
rel	optional `rel` attribute added when linking is enabled.
target	optional `target` attribute added when linking is enabled.
synonym	one or more alternative definition terms that map to the same definition.

Some keys may be repeated where that makes sense; for example, synonym may appear multiple times to add multiple synonyms.

Keys such as link, link-first, title, title-first, and synonym may be language-scoped using :lang (see Language handling).

Language handling

Definitions can be shared across languages or made language-specific.

Shared definitions

A definition written under [definitions] without language prefixes is applied to all languages, unless a language-specific definition overrides it.

Language-specific definitions

You can scope an entire definition to one or more languages by prefixing the definition name with one or more language codes separated by colons:

[definitions]

en:fr:Poutine
	type       = name
	link       = https://en.wikipedia.org/wiki/Poutine
	synonym:fr = poutine (plat)

The example above applies the definition Poutine to English and French.

Language-specific keys

Some keys can be set per language using key:lang = value. This is useful when the same definition exists in multiple languages but needs language-specific titles, links, or synonyms:

Term
	type          = default
	title:en      = English tooltip
	title:fr      = Info-bulle française
	link:en       = https://www.example.com/en/term
	link:fr       = https://www.example.com/fr/terme
	synonym:en    = Term (alt)
	synonym:fr    = Terme (alt)

Keys that affect link metadata (type, rel, target) are not language-scoped.

Using definition terms

In the article body, a definition term is written as {name} and must match a definition name or synonym exactly (including case). Definition terms can appear in most text contexts, including headings and link text (only for definitions that have no link defined).

Examples (valid):

<P>We will start with {Mycorrhiza} and then compare it to {Rhizome}.</P>

<H4>Using {Mycorrhiza} in the field</H4>

<P>Lookup more about <A href="https://example.org"> {Mycorrhiza}</A>.</P>

<P>Literal syntax: <CODE>{Mycorrhiza}</CODE>.</P>

Examples (invalid; do not do this):

<!-- Element name -->
<{term}>...</{term}>

<!-- Attribute value (would inject markup into an attribute) -->
<A href="https://example.org/{term}">Link</A>

Case prefixes and synonyms

Definition names and synonyms remain case-sensitive. {Term} therefore looks up Term, while {term} looks up term.

Since Nocterra 0.99.6, a definition term can use an explicit case prefix immediately after the opening brace. The prefix changes only the text that is rendered; the definition or synonym is still looked up using the exact text after the prefix.

Prefix	Effect
`_`	lowercase the first character (`lcfirst`)
`$`	uppercase the first character (`ucfirst`)
`-`	convert the complete value to lowercase (`strtolower`)
`+`	convert the complete value to uppercase (`strtoupper`)

For a definition named Term, the forms are therefore {Term}, {_Term}, {$Term}, {-Term}, and {+Term}. For example, {-Term} still looks up the definition named Term, but renders the occurrence as term.

Unlike placeholders and URL scheme keys, capitalization of the definition name itself does not imply a case prefix. {Term} means the exact definition or synonym Term; use {$term} only when term itself is the exact definition or synonym and its displayed value should start with an uppercase character. Placeholders, URL scheme keys, and definition terms share the case-prefix notation, but they are separate mechanisms and resolve their names to different kinds of values.

Use synonyms for genuinely different names or spellings rather than for case-only variants:

Term
	type    = default
	synonym = alternative term
	synonym = colour

The same case prefixes can also be applied when a synonym is used. The prefix operates on the synonym text written as the definition term while the synonym continues to use the markup of its canonical definition.

First occurrence behavior

Nocterra formats the first occurrence of a definition differently than subsequent occurrences. This allows the first occurrence to introduce the term (for example using <DFN> markup), while later occurrences use a lighter form (for example emphasis markup).

The “first occurrence” applies only to the canonical definition name. A synonym uses the normal occurrence markup and does not consume the canonical definition's first occurrence. Case-prefixed forms of the canonical name do count as that same canonical occurrence, because the prefix changes only the displayed text.

Example:

[definitions]

Nocturnal
	type    = default
	synonym = night-active

[body]

<P>{night-active} animals are easiest to observe at dusk.</P>
<P>Some {Nocturnal} species prefer deep forest cover.</P>

In the example above, {night-active} uses the normal occurrence formatting and does not consume the first occurrence. The later {Nocturnal} is the first canonical occurrence and therefore receives the “first occurrence” formatting.

Definition types

The type key controls which semantic markup is generated. Nocterra currently supports:

default — general terms, typically emitted as a definition on first occurrence and emphasis thereafter.
name — names (for example product names or publication titles), typically emitted using citation markup.
abbreviation — abbreviations, typically emitted using abbreviation markup.

Each type supports optional linking and tooltips:

If link (or link-first) is present, output is wrapped in an <A> element.
If title (or title-first) is present, a tooltip is emitted via the HTML title attribute.

Example definition set:

[definitions]

Nocterra
	type        = name
	link        = https://nocterra.org/
	title       = Nocterra documentation platform
	synonym     = Nocterra platform

ISO
	type        = abbreviation
	title       = International Organization for Standardization
	link        = https://www.iso.org/

mycorrhiza
	type        = default
	title       = Symbiosis between fungi and plant roots

Escaping literal braces

If you want to show the literal definition term syntax in an article (for example in a tutorial), do not write {term} directly. Instead, escape the braces so they are treated as literal text:

<P>Write a placeholder like this: {term}.</P>
<P>Or in code: <CODE>{term}</CODE>.</P>

This prevents Nocterra from treating the braces as a definition term.

Best practices and limitations

Keep definition names short and consistent. Prefer a single canonical name and add synonyms for variations.
Avoid using colons (:) in definition names, because colons are used to specify language prefixes.
Do not place definition terms inside HTML element names or attributes; definition term expansion inserts markup and may break output.
When in doubt, place the definition term in plain text content (inside a paragraph, heading, list item, or <CODE> element).

Definition keys reference

Each definition can contain one or more key/value pairs that control how the definition term is rendered in the article body. The tables below describe each supported key, including whether it can be repeated, whether it can be localized (using key:<lang_code>), and how “first occurrence” keys interact with their non-first variants.

`type`
Description:	Selects which semantic markup is used to render the term (see Definition types).
Required:	Optional
Repeatable:	Single
Localized:	No
Scope:	All
Condition:	None
Value:	Enumeration — supported values: `default` general terms `name` names of products, projects, people, or entities `abbreviation` abbreviations and acronyms Notes: If `type` is not set, it defaults to `default`.

`link`
Description:	Sets the URL used for linked occurrences of the term.
Required:	Optional
Repeatable:	Single
Localized:	Yes
Scope:	All
Condition:	Only used when linking is enabled (when `link` and/or `link-first` is set).
Value:	URL — absolute or relative URL. Notes: If only `link` is set, it is used for all occurrences (including the first). If both `link-first` and `link` are set, `link-first` is used for the first occurrence, and `link` is used for all other occurrences.

`link-first`
Description:	Sets an optional URL that is used for the first occurrence only.
Required:	Optional
Repeatable:	Single
Localized:	Yes
Scope:	First
Condition:	Only used when a first occurrence exists for that definition in the article body.
Value:	URL — absolute or relative URL. Notes: If `link-first` is set, it overrides `link` for the first occurrence. For all other occurrences, `link` is used (if set).

`title`
Description:	Sets an optional tooltip (`title` attribute) for occurrences of the term.
Required:	Optional
Repeatable:	Single
Localized:	Yes
Scope:	All
Condition:	None
Value:	String — tooltip text. Notes: If only `title` is set, it is used for all occurrences (including the first). If both `title-first` and `title` are set, `title-first` is used for the first occurrence, and `title` is used for all other occurrences.

`title-first`
Description:	Sets an optional tooltip (`title` attribute) for the first occurrence only.
Required:	Optional
Repeatable:	Single
Localized:	Yes
Scope:	First
Condition:	Only used when a first occurrence exists for that definition in the article body.
Value:	String — tooltip text. Notes: If `title-first` is set, it overrides `title` for the first occurrence. For all other occurrences, `title` is used (if set).

`rel`
Description:	Sets an optional `rel` attribute on generated links.
Required:	Optional
Repeatable:	Single
Localized:	No
Scope:	All
Condition:	Only when linking is enabled (when `link` and/or `link-first` is set).
Value:	String — space-separated `rel` tokens (for example: `noopener`, `noreferrer`).

`target`
Description:	Sets an optional `target` attribute on generated links.
Required:	Optional
Repeatable:	Single
Localized:	No
Scope:	All
Condition:	Only when linking is enabled (when `link` and/or `link-first` is set).
Value:	String — common values include `_blank`, `_self`, `_parent`, `_top`.

`synonym`
Description:	Adds one or more alternative definition terms that map to the same definition.
Required:	Optional
Repeatable:	Multiple
Localized:	Yes
Scope:	Mapping
Condition:	None
Value:	String — one synonym per key occurrence. Notes: Write the synonym without braces; the definition term in the body is written as `{synonym}`. Synonyms use the normal occurrence markup and do not consume the canonical definition's first occurrence.

Examples

This section contains two larger article file examples. Both include an article header, a [definitions] section, and a short body showing definition terms in practical use.

Example 1 — Single language article (English, flora/fauna)

author			= Rowan
published		= 2025-05-14
category		= Nature
tags			= Field notes, Plants, Fungi, Woodland
keywords		= mycorrhiza, oak woodland, Quercus robur, forest floor, fungi, root symbiosis, biodiversity, field observation
title			= Under the Oaks: A Short Guide to Mycorrhiza in the Wild
description		= A practical introduction to mycorrhiza and why fungi matter in oak woodlands, with easy observations you can try on a walk.

[definitions]

Mycorrhiza
	type        = default
	title       = Symbiosis between fungi and plant roots
	link        = https://en.wikipedia.org/wiki/Mycorrhiza
	synonym     = mycorrhiza

Quercus robur
	type        = name
	title       = English oak
	link        = https://en.wikipedia.org/wiki/Quercus_robur
	synonym     = English oak

ISO
	type        = abbreviation
	title       = International Organization for Standardization
	link        = https://www.iso.org/

[body]

<P>This article is a short field tutorial. We will look for signs of {Mycorrhiza} around {Quercus robur} and learn what to notice on the forest floor.</P>

<P>Literal syntax example: <CODE>{Mycorrhiza}</CODE>.</P>

<H4>Finding {Mycorrhiza} near {English oak}</H4>

<P>Start by checking the soil line and the leaf litter. If you see fine white strands near roots, you may be looking at fungal growth associated with {mycorrhiza}.</P>

<P>Want a reference link in the text? Read more about <A href="https://example.org/field-notes"> {Quercus robur}</A>.</P>

Example 2 — Dual language article (Canadian English + French, restaurant/cuisine)

author			= Camille
published		= 2025-06-02
category		= Cuisine
tags			= Restaurants, Regional food, Comfort food
keywords:en		= poutine, Québec cuisine, gravy, cheese curds, comfort food, regional specialties
keywords:fr		= poutine, cuisine québécoise, sauce brune, fromage en grains, spécialités régionales
title:en		= Poutine Basics: What to Order (and How to Talk About It)
title:fr		= Les bases de la poutine : quoi commander (et comment en parler)
description:en	= A short guide to poutine vocabulary and ordering tips, with a few terms defined inline.
description:fr	= Un petit guide du vocabulaire de la poutine et des conseils pour commander, avec quelques termes définis.

[definitions]

en:fr:Poutine
	type           = name
	title:en       = A Québec dish of fries, cheese curds, and gravy
	title:fr       = Plat québécois de frites, fromage en grains et sauce
	link:en        = https://en.wikipedia.org/wiki/Poutine
	link:fr        = https://fr.wikipedia.org/wiki/Poutine
	synonym:fr     = poutine

en:Cheese curds
	type           = default
	title          = Fresh curds that squeak when you bite
	link           = https://en.wikipedia.org/wiki/Cheese_curd

fr:Fromage en grains
	type           = default
	title          = Fromage frais qui “couine” sous la dent
	link           = https://fr.wikipedia.org/wiki/Fromage_en_grains

[body:en]
<P>This article is a short ordering tutorial. We will define a few words you will see on menus, starting with {Poutine}.</P>

%toc%

<H4>Ordering {Poutine} with confidence</H4>

<P>When a menu mentions {Cheese curds}, it usually means the classic topping. If you are unsure, ask the staff what they use.</P>


[body:fr]
<P>Ce guide est un petit tutoriel pour commander. Nous allons définir quelques mots, en commençant par {poutine}.</P>

%toc%

<H4>Commander une {Poutine} en toute confiance</H4>

<P>Quand le menu mentionne {Fromage en grains}, c’est généralement la garniture classique. En cas de doute, demandez au personnel.</P>