Elium reads and writes content as Markdown. This page is the reference for producing Markdown that Elium will import cleanly, whether you are pasting from another tool, migrating content in bulk, or generating it programmatically (for example from an AI model).

It is CommonMark plus a small set of widely-used extensions, with a {% … %} directive syntax for the rich blocks Markdown has no notation for (callouts, collapsible sections, galleries, embeds, file cards).

How it works

Supported Markdown

Everything below is recognized. "Inline" means it lives inside a line of text; "block" means it occupies its own line(s).

Feature	You write	Kind
Bold	`bold`	inline
Italic	`italic`	inline
Strikethrough	`~~strike~~`	inline
Inline code	`code`	inline
Link	`[label](https://example.com)`	inline
Image	`![alt](https://example.com/pic.png)`	inline
Subscript / superscript	`H~2~O` / `x^2^`	inline
Heading (1-3)	`# Title` / `## Section`	block
List	`- item` / `1. item`	block
Task list	`- [ ] todo` / `- [x] done`	block
Blockquote	`> quote`	block
Fenced code	```lang … ```	block
Table	pipe table	block
Horizontal rule	`---`	block
Footnote	`text[^1]` + `[^1]: …`	block

Soft line breaks inside a paragraph are kept, and bare URLs in text are auto-linked.

The directive model

Rich blocks with no Markdown equivalent use a paired open/close tag:

{% callout type="warning" %}
Content, written as normal Markdown.
{% endcallout %}

Options are space-separated name="value" pairs on the opening tag. Values may be quoted (title="A b"), bare if space-free (level=2), or omitted to mean true (collapsedByDefault). A missing boolean is false.
The body is Markdown and may nest other blocks, except literal blocks (code, embed, html), kept verbatim, and void blocks (image, references), written with an empty body.
Single-line form is allowed: {% callout %}Heads up.{% endcallout %}.

Plain Markdown first. If CommonMark can express something, use it (a heading is ## Title, not a directive). Directives carry only what CommonMark cannot: alignment, callout type, collapsible state, galleries, embeds, file references. Many blocks below therefore have two forms, and each says when the directive form is needed.

Elium normalizes your input

Elium accepts more than it produces. On import it understands option aliases (name/filename for a code title), multiple input forms (a language= option or a fenced info string), and HTML fallbacks. But it stores and re-emits a single canonical form, so your Markdown does not come back byte-for-byte:

a code block's language= option moves into the fenced info string;
option aliases are rewritten to their canonical name;
a simple table stays a pipe table, but one with spans/colors/widths is re-emitted as HTML.

Write whichever accepted form is convenient; expect the canonical form back.

What happens to the unrecognized

The format degrades predictably:

An unknown directive name ({% foo %}) stays as plain text.
Inline HTML outside the recognized set (see Text & inline formatting) is left literal.
A {% … %} tag indented four or more spaces is an indented code block, not a directive.
Unknown frontmatter keys make the whole block ordinary content, not metadata.

At a glance

Block	Plain Markdown	Directive	Reach for the directive when…
Heading	`## Title`	`{% heading %}`	it needs alignment
Paragraph	plain text	`{% paragraph %}`	it needs alignment
List & task list	`- item` / `- [ ]`	`{% check-list-item %}`	(rarely) a standalone checklist item
Blockquote	`> quote`	-	-
Table	pipe table	HTML `<table>`	it needs spans, colors, widths, or a heading column
Code	```lang … ```	`{% code %}`	it has a title or filename
Callout	-	`{% callout %}`	always
Collapse	-	`{% collapse %}`	always
Image	`![alt](url)`	`{% image %}`	it needs style, link, or sizing
File	-	`{% asset %}`	always
Gallery	-	`{% gallery %}`	always
Embed	-	`{% embed %}`	always
Linked content	-	`{% space/story/user/drive %}`	always
Raw HTML	-	`{% html %}`	always

Quick example

---
title: Release notes
showHeadingNumbers: true
--- 

# What's new

We shipped a few things this week.

{% callout type="info" %}
See the [changelog](https://example.com/log) for the full list.
{% endcallout %}

## Highlights

- [x] Faster import
- [ ] Dark mode

{% code title="upgrade.sh" %}
```bash
npm install elium@latest
```
{% endcode %}

Document frontmatter

A document may begin with a YAML frontmatter block of story- and document-level metadata. Only known keys count as metadata; an unknown key leaves the whole block as ordinary content.

---
title: Story title
showHeadingNumbers: true
summarized: false
---

# First heading

Supported keys: title, showHeadingNumbers, summarized, toc, truncationResult.

Text & inline formatting

The foundational layer, shared by every block that holds text.

Plain CommonMark covers most of it: **bold**, *italic*, ~~strike~~, `code`, [link](url), and ![alt](url). Elium adds:

Subscript H~2~O and superscript x^2^.
Footnotes: a [^label] reference (inline) and a matching [^label]: … definition (Markdown) collected at the foot of the content:
```
Elium imports CommonMark[^cm] and a few extensions.

[^cm]: The standard Markdown specification.
```

When inline content needs semantics CommonMark cannot represent, Elium uses a constrained set of inline HTML, which the importer understands:

Need	Markup
Underline	`<u>text</u>`
Sub / sup	`<sub>2</sub>` / `<sup>2</sup>`
Text / background color	`<span style="color: red">…</span>`
Tracked change (diff)	`<span data-diff="added">…</span>`
Mention	`<el-mention data-type="user" id="42">Jo</el-mention>`
Inline image with options	`<img src="…" width="700" height="316" data-mimetype="image/png">`
Inline asset	`<img data-asset-id="…" data-asset-type="FILE">`

A mention is the inline reference to a person, space, team, or story. Its text is the display name and data-type is one of user, space, team, story. Anything outside this recognized set stays as literal text.

Blocks

Every content block Elium supports, with its plain-Markdown form (where one exists) and its directive form. See At a glance for the index.

Heading

Section titles, levels 1-3.

Syntax

Plain Markdown: ## Section title

Directive (when aligned):

{% heading level=2 align="center" %}
Centered title
{% endheading %}

Options

Option	Values	Default	Aliases
`level`	`1`, `2`, `3`	`1`	-
`align`	`center`, `right`, `justify`, `inherit`, `end`	left	-

Content Inline Markdown.

Paragraph

A run of inline text. Use the directive only to set an alignment.

Syntax

Plain Markdown: ordinary text separated by a blank line.

Directive (when aligned):

{% paragraph align="right" %}
This paragraph is right-aligned.
{% endparagraph %}

Options

Option	Values	Default	Aliases
`align`	`center`, `right`, `justify`, `inherit`, `end`	left	-

Content Inline Markdown.

List & task list

Bulleted, numbered, and checkable lists.

Syntax

- bullet
- with a
  - nested item

1. first
2. second

- [ ] todo
- [x] done

A list mixing checked items with plain items is split into separate lists on import. A single checklist item can also be written as a directive ({% check-list-item checked %}Done{% endcheck-list-item %}), but - [x] is the normal form.

Content Each item holds inline Markdown and nested lists. Headings or tables inside a list item are flattened to plain text.

Blockquote

Quoted text.

Syntax

> A quoted line.
> A second line.

Content Inline Markdown; multiple lines join with line breaks.

Table

A grid of cells. A plain rectangular table is a pipe table; anything richer falls back to HTML.

Syntax

Plain Markdown: a CommonMark pipe table (escape a literal pipe in a cell as \|).
HTML fallback (column widths, cell spans, per-cell alignment/colors, a heading column, or block content in a cell): a raw <table>.

Options (HTML form)

Scope	Options
table	heading row/column, width/height, column widths, preset alignment
row	height
cell	`colspan`, `rowspan`, `align`, `valign`, width/height, background color, border color, heading flag

Content Each cell holds Markdown.

Example

| Name     | Character |
| -------- | --------- |
| Backtick | `         |
| Pipe     | \|        |

<table data-column-widths="120,-">
<tr>
<td>

Plain

</td>
<td align="center">

**Centered**

</td>
</tr>
</table>

Code

A fenced block of code, optionally with a title or filename.

Syntax

Plain Markdown (no title): a normal fenced block, language in the info string.
Directive (when it has a title or filename): the fenced block is wrapped in {% code %}.

Options

Option	Values	Default	Aliases
`title`	any string	-	`name`, `filename`
language	a language id	`plaintext`	set in the fence info string, or `language` / `lang`

The language travels in the fenced info string. The language option is also accepted on import; when both are present, the fence wins.

Content Literal. The body is kept verbatim, not reparsed as Markdown.

Example

```python
import re

def word_count(html: str) -> int:
    return max(len(re.sub(r"<[^>]+>", " ", html).split()), 1)
```

{% code title="word_count.py" %}
```python
import re

def word_count(html: str) -> int:
    return max(len(re.sub(r"<[^>]+>", " ", html).split()), 1)
```
{% endcode %}

Callout

A highlighted note or warning panel.

Syntax

{% callout type="warning" %}
Be careful: this action cannot be undone.
{% endcallout %}

Options

Option	Values	Default	Aliases
`type`	`info`, `warning`	`info`	-
`align`	`center`, `right`, `justify`, `inherit`, `end`	left	-

Content Inline Markdown.

Collapse

A collapsible section with a title and a body.

Syntax

{% collapse title="Frequently asked questions" level=2 collapsedByDefault %}
The body is normal Markdown and may contain any other blocks.
{% endcollapse %}

Options

Option	Values	Default	Aliases
`title`	plain-text title	-	-
`titleMarkdown`	formatted title	-	`titleMd`
`level`	`paragraph`, `1`, `2`, `3`	`paragraph`	-
`id`	anchor id	-	-
`align`	`center`, `right`, `justify`, `inherit`, `end`	left	-
`isTree`	boolean	`false`	-
`collapsedByDefault`	boolean	`false`	`collapsed`

Use title for a plain title, titleMarkdown when it needs inline formatting.

Content Any blocks. May also contain collapse-navigation links that jump to another section (options: to, the target id, and id):

{% collapse title="Question 1" %}
{% collapse-navigation to="question-2" %}Next question{% endcollapse-navigation %}

The answer goes here.
{% endcollapse %}

Image

Plain Markdown covers the simple case; the directive carries layout, links, and sizing.

Syntax

Plain Markdown: ![alt](url "title")
Directive (style/link/size): an empty {% image %}.

Options

Option	Values	Default	Aliases
`src`	image URL	-	`url`
`title`	caption / alt text	-	-
`link`	URL opened on click	-	-
`style`	`align-left`, `align-center`, `align-right`, `full-width`, `inline`, `banner`	-	-
`align`	`center`, `right`, `justify`, `inherit`, `end`	left	-
`width`, `height`	size	-	-
`originalWidth`, `originalHeight`	source size	-	-
`mimetype`	MIME type	`image/*`	-
`isExpanded`	boolean	`false`	-

Content Void.

Example

{% image src="https://example.com/photo.png" title="Sunset" style="full-width" width="1200" height="630" %}{% endimage %}

File

A reference to a stored Elium asset, shown as a card or preview.

Syntax

{% asset id="2f1c8e44-…" type="FILE" displayMode="card" %}{% endasset %}

Options

Option	Values	Default	Aliases
`id`	asset UUID	-	`asset`, `uuid`
`type`	asset type	`FILE`	-
`displayMode`	display mode	-	-
`style`	`align-left`, `align-center`, `align-right`, `full-width`, `inline`, `banner`	-	-
`align`	`center`, `right`, `justify`, `inherit`, `end`	left	-
`link`	URL opened on click	-	-
`caption`, `alt`	text	-	-
`width`, `height`, `originalWidth`, `originalHeight`, `assetWidth`, `assetHeight`	size	-	-
`isExpanded`	boolean	`false`	-

Content Void.

Gallery

A collection of images and/or assets laid out as a grid or list.

Syntax

{% gallery title="Vacation" layout="gallery" %}
{% image src="https://example.com/1.png" %}{% endimage %}

{% asset id="2f1c8e44-…" caption="Itinerary" %}{% endasset %}
{% endgallery %}

Options

Option	Values	Default	Aliases
`title`	any string	-	-
`layout`	`gallery` (grid), `list`	`gallery`	-

Content A series of image and/or asset directives, one per block, separated by blank lines.

Embed

Embedded external content (a player, a widget) expressed as HTML.

Syntax

{% embed height="420" scrolling="false" %}
<iframe src="https://example.com/player"></iframe>
{% endembed %}

Options

Option	Values	Default	Aliases
`height`	size	-	-
`scrolling`	boolean	`false`	-

Content Literal HTML, kept verbatim.

Linked content

Block boxes that link to an Elium entity. (For an inline person/space/story reference, use a mention instead.)

Syntax

{% space id="9b2e-…" %}{% endspace %}
{% story id="7c41-…" %}{% endstory %}
{% user id="42" %}{% enduser %}
{% drive folderId="1AbCdEf…" %}{% enddrive %}

Options

Box	Option
`space` / `story` / `user`	`id`
`drive`	`folderId`

Content Void.

Raw HTML

The escape hatch: arbitrary HTML for anything with no richer Elium block above.

Syntax

{% html %} <section class="hero">
Raw HTML content</section>
{% endhtml %}

Options None.

Content Literal HTML, kept verbatim.

Markdown input format

How it works

Supported Markdown

The directive model

Elium normalizes your input

What happens to the unrecognized

At a glance

Quick example

Document frontmatter

Text & inline formatting

Blocks

Heading

Paragraph

List & task list

Blockquote

Table

Code

Callout

Collapse

Image

File

Gallery

Embed

Linked content

Raw HTML