1.1Opening tag

An opening tag indicates the start of a Markdoc tag element that contains nested children. An opening tag’s TagInterior must include the name of the tag and can include zero or more tag attributes.

A tag may optionally have an unnamed PrimaryAttribute value following the Identifier:

Example № 3{% if $foo %}
This is a paragraph in an `if` tag.
{% /if %}

1.2Self-closing tag

A self-closing tag, indicated by a forward-slash at the end of the TagInterior, indicates a Markdoc tag element that does not contain nested children. A self-closing tag’s TagInterior must include the name of the tag and can include zero or more tag attributes.

1.3Closing tag

A closing tag, indicated by a forward-slash at the start of the TagInterior, indicates the end of a Markdoc tag element that contains nested children. A closing tag’s TagInterior may include include the name of the tag and optional trailing whitespace. A closing tag corresponds to the most recent opening tag that has the same tag name.

1.4Tag forms

Markdoc tags can be used as either block or inline elements in a Markdown document.

Example № 4{% foo %}
This is content inside of a block-level tag
{% /foo %}

Example № 5This is a paragraph {% foo %}that contains a tag{% /foo %}

Example № 6{% foo %}This is content inside of an inline tag{% /foo %}

1.5Annotation

An Annotation applies Attributes to the enclosing Markdown block. The attributes within the annotation are treated as though they are attributes on the document node itself. For example, an annotation can be used to add a CSS class to a heading node:

Example № 7# Heading {% .example %}

An Annotation may only be used as an inline document node. When an annotation appears on a line by itself, it is treated as though it is nested in a block-level paragraph element. Within an Annotation, each Attribute is separated by a space.

1.6Attributes

There are two types of attributes: full attributes (AttributeFull) and shorthand attributes (AttributeShorthand).

A full Attribute is a key-value pair that consists of an Identifier and a Value separated by an = sign. The Identifier serves as the Attribute‘s key. No whitespace is permitted between the tokens that make up an Attribute.

Example № 8{% foo="bar" baz=[1, 2, 3] %}

Example № 9{% #foo .bar %}

Example № 10{% id="foo" class="bar" %}

Example № 11{% .foo .bar .baz %}

Example № 12{% class="foo bar baz" %}

3.1Primitive values

3.2Compound values

Example № 14{% foo=[1, false, ["bar", $baz]] %}

Example № 15{% foo={key: "example value", "quoted key": $variable} %}

3.3Variable

A Variable allows Markdoc content to incorporate an external value. Variables may be used for Interpolation or in place of a value in tag attributes. Variables consist of multiple segments, which are intended to support accessing a value that is deeply nested in a complex data structure. A Variable segment can be an identifier or a square-bracket enclosed value. Determining how to resolve a Variable into a value is left up to individual Markdoc implementations.

Example № 16{% foo=$bar.baz[10].qux %}

3.4Function

A function consists of an Identifier followed by FunctionParameters enclosed in parentheses. Functions are used to incorporate external logic in a Markdoc document.

A FunctionParameter may be either a Value or a key-value pair separated by an equals sign. Functions may be used for Interpolation or in place of a value in tag attributes. Function parameters may be any valid Value, including a Variable or another Function. Determining how to evaluate a Function is left up to individual Markdoc implementations.