Parameters & invocation forms

A parameter is metadata that rides alongside a node's content — a link's address, an image's source, a recipe's serving count. There is one syntax: key: value pairs in parentheses glued to the name.

@img(src: lamp.png, alt: The second-order Fresnel lens)

<img src="lamp.png" alt="The second-order Fresnel lens">

The parentheses must touch the name. With a space between, they are prose: As @weil (1952) argued. is a reference followed by a year.

Values run to the next key

A value runs until the next key: that is a parameter of that node, so it may hold commas and colons. No quoting.

#recipe(dish, serves, note)
(h3 ::dish:: (serves ::serves::) h3)
::note::
recipe#

@recipe(dish: Leek and potato soup, serves: 4, note: Tip: sweat the leeks, don't brown them.)

<h3>Leek and potato soup (serves 4)</h3>
<p>Tip: sweat the leeks, don't brown them.</p>

Tip: is not a parameter of recipe, so it stays in the value. Parentheses inside a value balance, so @a(href: https://en.wikipedia.org/wiki/Mercury_(planet)) keeps its URL whole.

Positional values

A definition header lists parameters in order. Uses may then pass values by position, by name, or both — positional first.

#cite(author, year, page)
::author:: (::year::, p. ::page::)
cite#

As @cite(Arendt, 1958, page: 42) notes, and @cite(Sennett, 2008, 9).

<p>As Arendt (1958, p. 42) notes, and Sennett (2008, p. 9).</p>

A positional value cannot hold a comma: more pieces than declared parameters is E_TOO_MANY_ARGUMENTS — write @cite(author: Weil, S., year: 1952, page: 3) instead. Without a header, positional values are E_POSITIONAL_WITHOUT_HEADER; parameters are then inferred from the ::name:: placeholders and passed by name.

Across lines

Long parameter lists may span lines, one per line; commas are then optional.

@figure
@img(
  src: ./plates/heron.jpg
  alt: A grey heron, standing in shallow water
)
(figcaption Plate 3: the grey heron. figcaption)
figure@

<figure><img src="./plates/heron.jpg" alt="A grey heron, standing in shallow water"><figcaption>Plate 3: the grey heron.</figcaption></figure>

A blank line before the closing ) is E_UNCLOSED_PAREN, so a forgotten ) cannot swallow the rest of the document.

Parameters and a body

Parameters go on the opening tag; content goes in the body. A body is always content — it is never scanned for parameters.

See (a(href: https://tides.example.org) the tide tables a) before you sail.

<p>See <a href="https://tides.example.org">the tide tables</a> before you sail.</p>

The value-block use

When the body is long, @name(…): opens a block that !!, alone on its line, closes — no closing tag to find far below.

#exhibit(title, room)
@section
(h3 ::title:: — Room ::room:: h3)
::body::
section@
exhibit#

@exhibit(title: Northern Light, room: 4):
Twelve canvases painted over one winter on the Faroe Islands.

The last three were never shown in the artist's lifetime.
!!

<section><h3>Northern Light — Room 4</h3><p>Twelve canvases painted over one winter on the Faroe Islands.</p><p>The last three were never shown in the artist's lifetime.</p></section>

Elsewhere !! is two exclamation marks.

How values are read

By default a value is read as Wit, so emphasis and references work inside it. Mark a header parameter literal to use its value exactly as written — for commands, file globs and identifiers.

#shell(literal command, note)
(code ::command:: code) — ::note::
shell#

@shell(command: rm _cache_/*.tmp, note: clears the _build_ cache)

<p><code>rm _cache_/*.tmp</code> — clears the <em>build</em> cache</p>

Data as values

A value may be a reference or a data path; it passes the value itself.

#site: { logo: /img/logo.svg, name: Harbour Books } !!

@img(src: @site.logo, alt: @site.name)

<img src="/img/logo.svg" alt="Harbour Books">

Inside a loop the same works for each item — @metric(@m.label, @m.value) (see Iteration). A switch is a value too: @notice(urgent: true), tested with (if ::urgent::).

Core nodes' parameters

Core nodes declare their parameters like a definition header does.

(h2(id: methods) Methods h2)

renders <h2 id="methods">Methods</h2>. The full list is in Core vocabulary.

Errors

• E_MISSING_PARAM — a declared parameter was not passed.
• E_UNKNOWN_PARAM — the first key is not one the node declares (a later unknown key: just stays in the previous value).
• E_TOO_MANY_ARGUMENTS, E_POSITIONAL_WITHOUT_HEADER — positional values that cannot bind.
• E_UNCLOSED_PAREN — a blank line before ).

Older forms (pipes, braces after the name, space-separated keys) were removed in 0.3; see Syntax.

See also

Node use · Defining nodes · Interpolation & captures · Data · Core vocabulary