Wit

Defining nodes

#name … name# defines a node; @name uses it. Definitions are how you build a document's own vocabulary — callouts, citations, recipe cards, chapter openers.

Three shapes

  • Block — #name … name# around any number of lines.
  • Single-line — #name: value !! for a short value.
  • Value-block — #name:, then lines, then !! alone on a line.
source
#station: Ledbury Point !!
#epigraph:
The sea does not forgive forgetting.
— coastal proverb
!!

#warning
@aside
(strong Caution: strong) ::body::
aside@
warning#

Readings from @station.

@epigraph

@warning The gauge reads high after a storm surge. warning@
result

Readings from Ledbury Point.

The sea does not forgive forgetting. — coastal proverb

<p>Readings from Ledbury Point.</p>
<p>The sea does not forgive forgetting.
— coastal proverb</p>
<aside><p><strong>Caution:</strong> The gauge reads high after a storm surge.</p></aside>

Parameters and the body slot

Inside a definition, ::param:: inserts a parameter and ::body:: marks where the use's body goes. A header lists the parameters in order, so uses can pass them by position:

source
#chapter(number, title)
(h2 ::number:: — ::title:: h2)
::body::
chapter#

@chapter(III, The Long Watch)
The relief boat was nine days late.
chapter@
result

III — The Long Watch

The relief boat was nine days late.

<h2>III — The Long Watch</h2>
<p>The relief boat was nine days late.</p>

The header is optional. Without one, parameters are inferred from the ::name:: placeholders and must be passed by name:

source
#greeting
Dear ::name::, thank you for your order.
greeting#

@greeting(name: Ms Okafor)
result

Dear Ms Okafor, thank you for your order.

That renders Dear Ms Okafor, thank you for your order. A header also works on a single-line definition — #cite(author, year): ::author:: (::year::) !! — and can mark a parameter literal (see Parameters).

A definition without ::body:: takes no body, so its uses need no close. body is reserved for the slot, and ... is ordinary prose.

Order and reuse

Definitions are hoisted: a use may come before its definition. A definition body may use other definitions.

source
@byline

#author: Priya Nand !!
#byline
Written by @author for the spring issue.
byline#
result

Written by Priya Nand for the spring issue.

That renders Written by Priya Nand for the spring issue. A definition named after a core node — #aside, #h1 — replaces the core meaning for the whole document.

Data definitions

The single-line and value-block shapes also hold data: a record { … }, a collection [ … ], or a value-block whose lines are all key: value. See Data.

Errors

  • A definition inside (if …) or (each …) is E_CONDITIONAL_DEFINITION — put the condition inside the definition instead.
  • Defining the same name twice is E_DUPLICATE_DEFINITION, unless every entry is additive +#name (see Additive partials).
  • Giving a body to a use whose definition has no ::body:: is E_BODY_WITHOUT_SLOT.

Common mistakes

  • Writing ::name:: in prose — it only works inside a definition; in prose use @name.field.
  • Forgetting ::body:: in a wrapper like #warning — without it the use cannot take content.

See also

Parameters · Interpolation & captures · Additive partials · Node use