Attributes
The Attribute Syntax
Attributes are metadata that you can add to an existing element. They will always be enclosed in the { and } characters, and are very heavily inspired by pandoc’s attributes.
Here is a typical set of attributes:
{#example .definition title="Hello there" focus}
It consists of a list of space-separated attributes.
Attributes can be one of the following:
An identifier. This is represented with a
#followed by the name of the id. For instance:#examplerepresents the identifierexample.A class. This is represented with a
.followed by the name of the class. For instance:.definitionrepresents the classdefinition.A key-value attribute. This is represented by
key=value. For instancetitle=Hellois such an attribute. Single and double quotes can be used, allowing you to include spaces in the value.A flag attribute. It is an attribute that does not have a value, only a name. For instance,
focusis such an attribute.
Only a single identifier can be given to an element, and it must be unique amongst other elements. Multiple classes can be given to an element, and classes can be shared between elements, for example there might multiple .paragraph elements, but only one #introduction.
Key-value and flag attributes can be any of those defined in Actions or Special elements, or any valid HTML attribute.
Attaching metadata
Standalone attributes
A set of attributes that is separated from the rest of the content by blank lines is termed standalone. The attributes are attached to en “empty” element. It is useful in the context of Slipshow, to give an instruction (such as a pause) in the flow of the presentation, without being tied to a specific element.
Some text
{pause}
Some other text
Blocks and inlines
An important distinction needs to be made between inline and block elements.
Inlines are the elements that are within the flow of the text. For instance, bold text, links, italic, mathematic formulas.
Blocks, on the contrary, make the structure of the text. For instance paragraphs, titles, and bullet lists are blocks, as well as columns in a multi-column layout. Most of the time, they occupy the full horizontal width available.
This distinction is relevant here, as the way to add attributes is specific to each of the two cases, and sometimes it will be important to distinguish them.
Here is an example that sets the background of an element to red, through an attribute. In the first case, it’s attached to the whole paragraph. In the second case, it’s attached to the text of the paragraph.
This confusion happens often with metadata for images.
Block metadata
To attach attributes to a block, put the curly braces on an (otherwise empty) line just above it. For example, for a heading:
{the attributes}
# The title
If you want to attach an attribute to a group of several blocks, use grouping. For instance, indent all of them using >:
{the attributes}
> Some text
>
> ```
> A code block
> ```
An attribute cannot have line breaks. However, if two or more lines of attributes are consecutive, they will be merged.
Inline metadata
For setting attributes on inline elements, the syntax is quite similar: attributes are enclosed in curly braces. What changes is how they are attached to a specific element.
Attributes are attached to the inline element they touch (before or after). For instance:
Some text and{A} some {B}other text and {C} finally an end.
Works with **bold**{D} and other `inline elements`{E}
In this example, A is attached to and, B to other, C is a standalone inline attribute, D is attached to **bold** and E to `inline elements`.
To attach an attribute to a group of inlines, use the square-bracket […]{attributes} grouping syntax. For instance:
Works with [groups of **bold** and other `inline elements`]{F}
However, sometimes putting long attributes in the middle of the text can hurt readability. Often, the attributes are the same and are repeated, which makes it even worse. Slipshow eases this by using referenced attributes. Much like footnotes and referenced links, their text only contains a reference, and the attribute itself is defined elsewhere:
Some [text][A] [with][A] [many][A] [attributed][A] [words][A].
[A]: {many long attributes}
Not perfect, but much better than setting the same attributes on every element separately.
Metadata for images
Attaching metadata to images is a good example of where the distinction between blocks and inline is relevant, but is also confusing.
Consider the following small piece of markup:
Have a look at the following image:
Images are inline elements (they can be included in the middle of text), but this one is the only element of a block (a paragraph here). So, there are two ways to attach attributes to it: as an inline element, or as a block element.
We illustrate these two possibilities by adding borders to the element on which the attributes are applied:
Both approaches can be useful. For instance, centering the image is a property of the containing block, while the width of the image is a property of itself. So pay attention when assigning attributes to images!