Attributes let you set an element’s id, its classes, and any other HTML attribute from Markdown, by writing them in braces after the element. Use attributes to give a heading an id that stays put when its text changes, to size an image, or to mark a code block for a script or stylesheet to find.

Comrak’s attributes follow the attributes extension of commonmark-hs, which Pandoc also uses. Comrak supports attributes on four kinds of element, each with its own extension: headings, fenced code blocks, code spans, and links and images. This document describes all four, and Differences from commonmark-hs lists where Comrak parts ways.

To enable attributes on headings, pass -e header-attributes on the command line, or set extension.header_attributes in the options struct. The other three are -e fenced-code-attributes (extension.fenced_code_attributes), -e inline-code-attributes (extension.inline_code_attributes), and -e link-attributes (extension.link_attributes).

The extensions only parse attributes into the AST. HTML output includes them only when you also pass both --attributes and --unsafe, as described in Render attributes. Any attribute can be turned against the page it’s on — onclick runs script, and even an id or a class can interfere with the page’s own scripts and styles — so if you render untrusted input with attributes, sanitise the result.

Here’s a typical use of attributes:

Example 1
$ comrak -e header-attributes -e inline-code-attributes -e link-attributes --attributes --unsafe
# Installation {#install}

Run `cargo install comrak`{.shell}, then read [the docs]https://comrak.ee{target=_blank}.

Syntax

An attribute block is {, followed by any number of attributes, followed by }. Whitespace — spaces, tabs, and line endings — separates attributes, and may also follow { and precede }.

An attribute is one of:

The examples in this section put attribute blocks on code spans; Code spans describes where an attribute block goes. Here’s an attribute block with one attribute of each kind:

Example 2
$ comrak -e inline-code-attributes --attributes --unsafe
`hello`{#greeting .code lang=en}

An attribute block may be empty, and may span lines:

Example 3
$ comrak -e inline-code-attributes --attributes --unsafe
`a`{} `b`{ #x
.y
k=v }

Text in braces that doesn’t follow these rules isn’t an attribute block, and remains text. None of these are attribute blocks:

Example 4
$ comrak -e inline-code-attributes --attributes --unsafe
`a`{#} `b`{key} `c`{key=} `d`{key = value} `e`{.x,.y}

Values

A value is a bare value or a quoted value.

In an id or class attribute, a bare value is one or more ASCII letters, digits, -, _, :, ., or %. In a key–value attribute, a bare value may be any characters other than whitespace, ", ', =, <, >, `, and }:

Example 5
$ comrak -e inline-code-attributes --attributes --unsafe
`a`{#top .x-1 data-src=../img/cat.png}

A quoted value is ", followed by any characters, followed by ". A quoted value may contain whitespace, including line endings, and a backslash escapes any character, including " and \:

Example 6
$ comrak -e inline-code-attributes --attributes --unsafe
`a`{title="Say \"hi\"" #"two words"}

A quoted value must be followed by whitespace or }:

Example 7
$ comrak -e inline-code-attributes --attributes --unsafe
`a`{k="v".c}

Entity references are decoded in any value, unless a backslash escapes their &:

Example 8
$ comrak -e inline-code-attributes --attributes --unsafe
`a`{k=caf&eacute; l="&amp;" m="\&amp;"}

Keys

A key is an ASCII letter, _, or :, followed by any number of ASCII letters, digits, -, _, :, and .:

Example 9
$ comrak -e inline-code-attributes --attributes --unsafe
`a`{data-x=1 _k=2 xml:lang=en} `b`{1k=v}

Conflicts

An element has at most one id. If an attribute block has more than one id attribute, the last one takes precedence. A key–value attribute with the key id counts as an id attribute:

Example 10
$ comrak -e inline-code-attributes --attributes --unsafe
`a`{#one #two id=three}

Class attributes accumulate, and a key–value attribute with the key class adds its value to them:

Example 11
$ comrak -e inline-code-attributes --attributes --unsafe
`a`{.one class="two three" .four}

For any other key, the last key–value attribute with that key takes precedence. Keys are compared without regard to ASCII case, like HTML compares attribute names:

Example 12
$ comrak -e inline-code-attributes --attributes --unsafe
`a`{k=1 l=2 K=3}

Headings

With -e header-attributes, an attribute block at the end of an ATX heading or a setext heading applies to the heading. Whitespace must separate the attribute block from the heading’s text:

Example 13
$ comrak -e header-attributes --attributes --unsafe
# Heading {#a}

Heading {#b}
-------

# Heading{#c}

Whitespace may follow the attribute block, as may an ATX heading’s closing sequence. A closing sequence before the attribute block is part of the heading’s text:

Example 14
$ comrak -e header-attributes --attributes --unsafe
# Heading {#a} #

# Heading # {#b}

The attribute block must end the heading, and only the last one counts:

Example 15
$ comrak -e header-attributes --attributes --unsafe
# Heading {#a} text

# Heading {#b} {.c}

In a setext heading over more than one line, the attribute block must end the last line. It may be the last line on its own:

Example 16
$ comrak -e header-attributes --attributes --unsafe
First {#a}
second
======

First
second
{#b}
======

A heading may consist of an attribute block alone:

Example 17
$ comrak -e header-attributes --attributes --unsafe
# {#empty}

Comrak recognises the attribute block in the heading’s text as written, before inline parsing, so a backslash escape or an entity reference can’t form one:

Example 18
$ comrak -e header-attributes --attributes --unsafe
# Heading \{#a}

# Heading &#123;#b}

Fenced code blocks

With -e fenced-code-attributes, an attribute block at the end of a fenced code block’s info string applies to the code block. The first word of the rest of the info string gives the language, as usual:

Example 19
$ comrak -e fenced-code-attributes --attributes --unsafe
```rust {#main .numbered}
fn main() {}
```

The attribute block may be the whole info string:

Example 20
$ comrak -e fenced-code-attributes --attributes --unsafe
```{#main}
fn main() {}
```

Whitespace must come before the attribute block if anything precedes it, and only whitespace may follow it. Otherwise, the attribute block is part of the info string:

Example 21
$ comrak -e fenced-code-attributes --attributes --unsafe
```rust{#a}
fn main() {}
```

```rust {#b} more
fn main() {}
```

Comrak recognises the attribute block in the info string as written, before it interprets backslash escapes and entity references, so neither can form one:

Example 22
$ comrak -e fenced-code-attributes --attributes --unsafe
```rust \{#a}
fn main() {}
```

Code spans

With -e inline-code-attributes, an attribute block directly after a code span applies to it. Nothing may come between them, including spaces of any kind:

Example 23
$ comrak -e inline-code-attributes --attributes --unsafe
`a`{#x} and `b` {#y}

An attribute block may span lines, within the code span’s paragraph:

Example 24
$ comrak -e inline-code-attributes --attributes --unsafe
`a`{#x
.y}

Consecutive attribute blocks apply together, as if they were one:

Example 25
$ comrak -e inline-code-attributes --attributes --unsafe
`a`{#x .y}{.z #w}

With -e link-attributes, an attribute block directly after a link or an image applies to it. The attribute block goes after the link’s destination, or after a reference link’s last ]:

Example 26
$ comrak -e link-attributes --attributes --unsafe
[inline]/a{#a} [full][ref]{#b} [collapsed][]{#c} [ref]{#d}

[ref]: /r
[collapsed]: /c
Example 27
$ comrak -e link-attributes --attributes --unsafe
![A cat]cat.png{width=320 .photo}

CommonMark autolinks don’t take attributes:

Example 28
$ comrak -e link-attributes --attributes --unsafe
<https://comrak.ee>{#x}

A link’s text may contain a code span or an image with attributes of its own:

Example 29
$ comrak -e inline-code-attributes -e link-attributes --attributes --unsafe
[`comrak`{.name} ![logo]comrak.png{width=16}]https://comrak.ee{.home}

Output

HTML output includes attributes only with both --attributes and --unsafe. Comrak writes the id first, then the classes, then the key–value attributes in order. Values are escaped as HTML attribute values:

Example 30
$ comrak -e inline-code-attributes --attributes --unsafe
`a`{k=v .x title="<b> & </b>" #y}

Where Comrak writes an attribute of its own, that attribute takes precedence, and Comrak ignores any attribute of the same name from the attribute block. Comrak’s own attributes include a link’s href and title, an image’s src, alt, and title, a heading’s generated id, and data-sourcepos:

Example 31
$ comrak -e link-attributes --attributes --unsafe
[a]/u "Title"{href=/v title=Other data-x=1} [b]/u{title=Used}

A code block’s attributes go on its <pre> element. Classes from the attribute block join any class the syntax highlighter gives the <pre> element, as in example 19.

Heading adapters and code fence renderers, which a program using Comrak as a library can provide, don’t receive attributes. Syntax highlighters do.

CommonMark output writes attribute blocks back. It writes each value bare where it can, and quoted otherwise. In a quoted value, it puts a backslash before " and \, and writes & and line endings as entity references. It also escapes a { that would otherwise begin an attribute block, such as one straight after a code span or anywhere in a heading. This example’s CommonMark view shows both:

Example 32
$ comrak -e header-attributes -e inline-code-attributes --attributes --unsafe
# Braces \{like this} {#braces}

`a`{k="two words"}\{.literal}

XML output doesn’t include attributes.

In the AST, a node’s attributes are in its Ast’s attrs field, an Attributes holding the id (id), the classes (classes), and the key–value attributes (pairs). Comrak parses attributes into the AST whenever their extension is enabled, regardless of render options, meaning custom formatters always see them.

An element’s source position covers its attribute blocks:

Example 33
$ comrak -e inline-code-attributes --attributes --unsafe --sourcepos
`a`{#x
.y} b

Options

Render attributes

With --attributes (render.attributes) and --unsafe (render.r#unsafe), HTML output includes attributes. Without --unsafe, they aren’t included in HTML output, but are still parsed, so they don’t appear as text either. With --attributes alone:

Example 34
$ comrak -e inline-code-attributes --attributes
`a`{#x .y}

With both:

Example 35
$ comrak -e inline-code-attributes --attributes --unsafe
`a`{#x .y}

Interactions

--gfm doesn’t enable attributes:

Example 36
$ comrak --gfm --attributes --unsafe
# Heading {#a}

With --header-id-prefix, an id attribute replaces a heading’s generated id, and gets the prefix too. Generated ids avoid any id given by an attribute, wherever it appears in the document:

Example 37
$ comrak -e header-attributes --header-id-prefix user-content- --attributes --unsafe
# Hi!
# Hi! {#hi}
# Hi! {#greeting .wave}

With --github-pre-lang, the language goes in the <pre> element’s lang attribute, meaning a lang key–value attribute is ignored:

Example 38
$ comrak -e fenced-code-attributes --github-pre-lang --attributes --unsafe
```rust {#main lang=fr}
fn main() {}
```

With --full-info-string, the words after the language, other than the attribute block, go in the data-meta attribute:

Example 39
$ comrak -e fenced-code-attributes --full-info-string --attributes --unsafe
```rust ignore {#main}
fn main() {}
```

With --default-info-string, a code block whose info string is only an attribute block gets the default language:

Example 40
$ comrak -e fenced-code-attributes --default-info-string rust --attributes --unsafe
```{#main}
fn main() {}
```

With code maths, inline code maths doesn’t take attributes:

Example 41
$ comrak -e inline-code-attributes -e math-code --attributes --unsafe
$`x^2`${#x}

A maths code block takes them like any other fenced code block does:

Example 42
$ comrak -e fenced-code-attributes -e math-code --attributes --unsafe
```math {#euler}
e^{i\pi} + 1 = 0
```

With wikilinks, a wikilink doesn’t take attributes:

Example 43
$ comrak -e link-attributes -e wikilinks-title-after-pipe --attributes --unsafe
[[Home]]{#x}

With tables, escape | in a value as in any other cell content:

Example 44
$ comrak -e table -e inline-code-attributes --attributes --unsafe
| a |
| - |
| `x`{title="p\|q"} |

With --smart, values keep their punctuation as written:

Example 45
$ comrak -e inline-code-attributes --smart --attributes --unsafe
`a`{title="it's -- \"fine\""}

Differences from commonmark-hs

Pandoc uses commonmark-hs’s attributes extension; the comparison here is with Pandoc 3.7. Pandoc always renders attributes, and its other extensions and options differ from Comrak’s, so the examples under Options and Interactions, and those with source positions, aren’t comparable. Pandoc’s HTML output also differs in ways that don’t concern attributes: it puts a code block’s language in the <pre> element’s classes, and it adds data- to keys that aren’t standard HTML attributes.

On every other example above, Pandoc and Comrak align, except that Pandoc:

commonmark-hs’s own specification says the last id attribute takes effect, as in Comrak, suggesting Pandoc does something after the fact.

commonmark-hs also allows attributes where Comrak doesn’t: after any inline element, such as emphasis; at the end of a link reference definition, for every link that uses it; and on a line of their own before a block.

Regressions

The following examples guard against regressions.

Source positions of attribute blocks that span lines, after an image and a code span (#902):

Example 46
$ comrak -e link-attributes -e inline-code-attributes --attributes --unsafe --sourcepos
a
b ![](x){w=1
   h=2} c `d` e
Example 47
$ comrak -e inline-code-attributes --attributes --unsafe --sourcepos
a
`x`{w=1
  h=2} b

Source positions of a link whose destination starts on a later line (#908):

Example 48
$ comrak -e link-attributes --attributes --unsafe --sourcepos
[a](
/u){.c} x