Directives

Directives are a markdown syntax extension that allow custom elements to be mixed in with the core markdown elements provided by the CommonMark spec.

Alt Text Editor uses directives to represent Confluence-specific elements not covered by CommonMark, such as styles, links, macros, and more.

Syntax

A directive for underlined content looks like this:

:style[some text here]{.underline}

Directives contain the following parts:

  • The Flow Symbol(s) - The number of colons (:) at the beginning of the directive. (See below for more details on flow)
  • Name - The name of the directive, or element. In the above example, style. Other examples include macro and emoji
  • Body - The portion between the brackets ([]). Usually, the content that the directive applies to, but in some cases, special instructions to the directive. some text here in the above example
  • Attributes - The portion between the braces ({}). Usually, data that helps the directive do the right thing. In the above, the .underline attribute instructs the style directive on how to format the text in the Body

Most of the time, the usage of each will feel natural in the context the directive is used, but where there is a more complex scenario, check the documentation specific to that element.

Flow

The Flow of a directive is used to indicate that it should exist in an inline (usually within a line or paragraph) or that it should exist across a block context (multiple lines or other blocky elements).

When Alt Text Editor is first opened, and the page's Storage Format is converted to Markdown for editing, it will just do the right thing and use the right flow.

If crafting directives from scratch in Markdown, the below examples should be illustrative.

Inline

For styling in-line elements using directives with a single colon (:)

This is a sentence where some :style[text is underlined]{.underline}

Block

For styling multi-line elements using directives with triple colons (:::) that wrap other block content

:::style{color=rgb(76,154,255)}
* Blue Whale
* Blue Sea
:::

Inline, but Blocky (Defs)

Sometimes it takes multiple lines of markdown to describe an element that is being used in an inline context. In these cases, Alt Text Editor will extract the multiline portion of the directive and push it into a def block directive at the end of the document. This allows for an inline placeholder, or pointer, to the def, or definition, of the directive to remain inline.

An example from the macro documentation will help illustrate this:

Examine the below Storage Format. Notice how this pets macro is providing a count visual of some kind that is meant to exist within a paragraph (an inline flow context), presumably to render something like You have 9 pets!

<p>You have <ac:structured-macro ac:name="pets">
  <ac:parameter ac:name="animal">cat</ac:parameter>
</ac:structured-macro> pets!</p>

If Alt Text Editor builds markdown for the above when it is loaded, it needs to maintain that inline flow context. To do so, it uses the inline (single colon) version of the macro directive and puts the multi-line content into an associated macrodef def at the bottom of the document.

You have :macro[pets]{#1} pets!

...the rest of your page's content...

:::macrodef[pets]{defId=1}
```params
animal=cat
```
:::

This allows the You have 9 pets! content to remain correctly in an inline flow, while also allowing the usage of multi-line markdown syntax.

Alt Text Editor takes care of all of this for you, so don't worry about crafting this yourself - but when working with macros you will see this fairly often.

See Also

For more examples, see Links, Macros, or any other page in the guide where that page's element is directive-based.