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:
$ comrak -e header-attributes -e inline-code-attributes -e link-attributes --attributes --unsafe -t commonmark -t xml
Installation
Run cargo install comrak, then read the docs.
Installation
Run cargo install comrak, then read the docs.
Installation
Run
cargo install comrak
, then read
the docs
.
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:
- an id attribute, which is
#followed by a value; - a class attribute, which is
.followed by a value; or, - a key–value attribute, which is a key,
=, and a value.
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:
$ comrak -e inline-code-attributes --attributes --unsafe -t commonmark -t xml
hello
hello
hello
An attribute block may be empty, and may span lines:
$ comrak -e inline-code-attributes --attributes --unsafe -t commonmark -t xml
a b
a b
a
b
Text in braces that doesn’t follow these rules isn’t an attribute block, and remains text. None of these are attribute blocks:
$ comrak -e inline-code-attributes --attributes --unsafe -t commonmark -t xml
a{#} b{key} c{key=} d{key = value} e{.x,.y}
a{#} b{key} c{key=} d{key = value} e{.x,.y}
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 }:
$ comrak -e inline-code-attributes --attributes --unsafe -t commonmark -t xml
a
a
a
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 \:
$ comrak -e inline-code-attributes --attributes --unsafe -t commonmark -t xml
a
a
a
A quoted value must be followed by whitespace or }:
$ comrak -e inline-code-attributes --attributes --unsafe -t commonmark -t xml
a{k="v".c}
a{k="v".c}
a
{k="v".c}
Entity references are decoded in any value, unless a backslash escapes their &:
$ comrak -e inline-code-attributes --attributes --unsafe -t commonmark -t xml
a
a
a
Keys
A key is an ASCII letter, _, or :, followed by any number of ASCII letters, digits, -, _, :, and .:
$ comrak -e inline-code-attributes --attributes --unsafe -t commonmark -t xml
a b{1k=v}
a b{1k=v}
a
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:
$ comrak -e inline-code-attributes --attributes --unsafe -t commonmark -t xml
a
a
a
Class attributes accumulate, and a key–value attribute with the key class adds its value to them:
$ comrak -e inline-code-attributes --attributes --unsafe -t commonmark -t xml
a
a
a
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:
$ comrak -e inline-code-attributes --attributes --unsafe -t commonmark -t xml
a
a
a
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:
$ comrak -e header-attributes --attributes --unsafe -t commonmark -t xml
Heading
Heading
Heading{#c}
Heading
Heading
Heading{#c}
Heading
Heading
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:
$ comrak -e header-attributes --attributes --unsafe -t commonmark -t xml
Heading
Heading #
Heading
Heading #
Heading
Heading #
The attribute block must end the heading, and only the last one counts:
$ comrak -e header-attributes --attributes --unsafe -t commonmark -t xml
Heading {#a} text
Heading {#b}
Heading {#a} text
Heading {#b}
Heading {#a} text
Heading {#b}
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:
$ comrak -e header-attributes --attributes --unsafe -t commonmark -t xml
First {#a} second
First second
First {#a}
second
First
second
First {#a}
second
First
second
A heading may consist of an attribute block alone:
$ comrak -e header-attributes --attributes --unsafe -t commonmark -t xml
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:
$ comrak -e header-attributes --attributes --unsafe -t commonmark -t xml
Heading {#a}
Heading {#b}
Heading {#a}
Heading {#b}
Heading {#a}
Heading {#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:
$ comrak -e fenced-code-attributes --attributes --unsafe -t commonmark -t xml
fn main() {}
fn main() {}
The attribute block may be the whole info string:
$ comrak -e fenced-code-attributes --attributes --unsafe -t commonmark -t xml
fn main() {}
fn 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:
$ comrak -e fenced-code-attributes --attributes --unsafe -t commonmark -t xml
fn main() {}
fn main() {}
fn main() {}
fn main() {}
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:
$ comrak -e fenced-code-attributes --attributes --unsafe -t commonmark -t xml
fn main() {}
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:
$ comrak -e inline-code-attributes --attributes --unsafe -t commonmark -t xml
a and b {#y}
a and b {#y}
a
and
b
{#y}
An attribute block may span lines, within the code span’s paragraph:
$ comrak -e inline-code-attributes --attributes --unsafe -t commonmark -t xml
a
a
a
Consecutive attribute blocks apply together, as if they were one:
$ comrak -e inline-code-attributes --attributes --unsafe -t commonmark -t xml
a
a
a
Links and images
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 ]:
$ comrak -e link-attributes --attributes --unsafe -t commonmark -t xml
$ comrak -e link-attributes --attributes --unsafe -t commonmark -t xml

A cat
CommonMark autolinks don’t take attributes:
$ comrak -e link-attributes --attributes --unsafe -t commonmark -t xml
A link’s text may contain a code span or an image with attributes of its own:
$ comrak -e inline-code-attributes -e link-attributes --attributes --unsafe -t commonmark -t xml
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:
$ comrak -e inline-code-attributes --attributes --unsafe -t commonmark -t xml
a
a
a
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:
$ comrak -e link-attributes --attributes --unsafe -t commonmark -t xml
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:
$ comrak -e header-attributes -e inline-code-attributes --attributes --unsafe -t commonmark -t xml
Braces {like this}
a{.literal}
Braces {like this}
a{.literal}
Braces {like this}
a
{.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:
$ comrak -e inline-code-attributes --attributes --unsafe --sourcepos -t commonmark -t xml
a b
a b
a
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:
$ comrak -e inline-code-attributes --attributes -t commonmark -t xml
a
a
a
With both:
$ comrak -e inline-code-attributes --attributes --unsafe -t commonmark -t xml
a
a
a
Interactions
--gfm doesn’t enable attributes:
$ comrak --gfm --attributes --unsafe -t commonmark -t xml
Heading {#a}
Heading {#a}
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:
$ comrak -e header-attributes --header-id-prefix user-content- --attributes --unsafe -t commonmark -t xml
With --github-pre-lang, the language goes in the <pre> element’s lang attribute, meaning a lang key–value attribute is ignored:
$ comrak -e fenced-code-attributes --github-pre-lang --attributes --unsafe -t commonmark -t xml
fn main() {}
fn main() {}
With --full-info-string, the words after the language, other than the attribute block, go in the data-meta attribute:
$ comrak -e fenced-code-attributes --full-info-string --attributes --unsafe -t commonmark -t xml
fn main() {}
fn main() {}
With --default-info-string, a code block whose info string is only an attribute block gets the default language:
$ comrak -e fenced-code-attributes --default-info-string rust --attributes --unsafe -t commonmark -t xml
fn main() {}
fn main() {}
With code maths, inline code maths doesn’t take attributes:
$ comrak -e inline-code-attributes -e math-code --attributes --unsafe -t commonmark -t xml
x^2{#x}
x^2{#x}
x^2
{#x}
A maths code block takes them like any other fenced code block does:
$ comrak -e fenced-code-attributes -e math-code --attributes --unsafe -t commonmark -t xml
e^{i\pi} + 1 = 0
e^{i\pi} + 1 = 0
e^{i\pi} + 1 = 0
With wikilinks, a wikilink doesn’t take attributes:
$ comrak -e link-attributes -e wikilinks-title-after-pipe --attributes --unsafe -t commonmark -t xml
With tables, escape | in a value as in any other cell content:
$ comrak -e table -e inline-code-attributes --attributes --unsafe -t commonmark -t xml
| a |
|---|
x |
a
x
a
x
With --smart, values keep their punctuation as written:
$ comrak -e inline-code-attributes --smart --attributes --unsafe -t commonmark -t xml
a
a
a
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:
- leaves an empty attribute block as text (example 3);
- doesn’t allow quoted ids or classes, or backslash escapes in quoted values (example 6, example 8);
- keeps the first id attribute and the first key–value attribute with each key, rather than the last, and compares keys case-sensitively (example 10, example 12, example 25);
- applies an attribute block that follows text or a space to a span around that text or space (example 13, example 15, example 16, example 23);
- does not recognise attributes in a heading that is only an attribute block (example 17);
- recognises an attribute block straight after a code block’s language, and one formed by backslash escapes (example 21, example 22);
- recognises attributes on autolinks (example 28); and,
- writes an attribute that repeats one of its own, such as a second
href(example 31).
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):
$ comrak -e link-attributes -e inline-code-attributes --attributes --unsafe --sourcepos -t commonmark -t xml
a
b c
d e
a
b c d e
a
b
c
d
e
$ comrak -e inline-code-attributes --attributes --unsafe --sourcepos -t commonmark -t xml
a
x b
a
x b
a
x
b
Source positions of a link whose destination starts on a later line (#908):
$ comrak -e link-attributes --attributes --unsafe --sourcepos -t commonmark -t xml