Nocterra

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 term placeholder 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 placeholders, 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 placeholder must not be used inside an HTML element name or inside an attribute name/value. Placeholders 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 placeholders unless you explicitly provide synonyms (see Case 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 placeholders 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 placeholders

In the article body, a definition placeholder is written as {name} and must match a definition name or synonym exactly (including case). Placeholders 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 and synonyms

Definition placeholders are case-sensitive. This means {Term} and {term} are treated as different placeholders.

To support different spellings or casing, add synonyms:


			Term
				type    = default
				synonym = term
				synonym = TERM

Synonyms are useful for:

case variants (Term vs term),
alternative spellings (colour vs color),
and abbreviations that should expand using the same formatting.

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” is tracked per definition as a whole. If a synonym is used first, that synonym counts as the first occurrence for the definition, and later uses of the main term are treated as subsequent occurrences.

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, the first paragraph will use the “first occurrence” formatting for the definition, even though the synonym was used instead of the main name.

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 placeholder 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 placeholder.

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 placeholders inside HTML element names or attributes; placeholder expansion inserts markup and may break output.
When in doubt, place the placeholder 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 placeholder 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 placeholders 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 placeholder in the body is written as `{synonym}`. First-occurrence behavior is tracked per definition: the first occurrence of the term or any of its synonyms is treated as the “first occurrence”.

Examples

This section contains two larger article file examples. Both include an article header, a [definitions] section, and a short body showing placeholders 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>