adf-codec/spec/html.md

The HTML dialect

The HTML adfToHtml writes: semantic elements for the nodes and marks below, and the carry element for every other node (docs/decisions.md §The HTML dialect). The written form is contract (docs/decisions.md §The formats are API).

Blocks

One block a line: blocks are separated by a line feed, and a document holding any ends with one. A document whose content is an empty array is the empty string.

ADF	HTML
paragraph	<p>…</p>
heading, level 1 to 6	<h1>…</h1> to <h6>…</h6>
blockquote	<blockquote>, a line feed, its blocks, a line feed, </blockquote>
bulletList	<ul>, a line feed, its items a line each, a line feed, </ul>
orderedList	as bulletList with <ol>; <ol start="3"> for an order of 3, a safe integer; no start where the list holds no order
listItem	<li>…</li>: a first paragraph holding content bare, its inline content straight after <li>, then each other block after a line feed and a line feed before </li>; with no bare paragraph, <li>, a line feed, its blocks, a line feed, </li>
codeBlock	<pre><code class="language-js">…</code></pre>, the language one token holding no whitespace; no class where it holds no language
rule	<hr>
mediaSingle, centered, holding one external media	<p><img src="…" alt="…"></p>, no alt where the media holds none; <p><a href="…"><img …></a></p> where a link marks it

A container holding no content key is its element holding nothing: <blockquote></blockquote>, <ul></ul>, <li></li>; so is a paragraph or heading, <p></p>.

Inline

ADF	HTML
text	its text, escaped
em, strong, code	<em>, <strong>, <code> around the text
link, holding href and an optional title	<a href="…" title="…"> around the text
hardBreak	<br>

A text node's marks nest in the order its marks array lists them, the first outermost: <strong><em>manual</em></strong>. Each text node writes its own elements, so two text nodes a link marks are two <a> elements.

Escaping

Text and attribute values escape &, <, > and " as &, <, > and ", and a carriage return as 
, which an HTML parser would otherwise read as a line feed. Attribute values are double-quoted. A link's href and an image's src are the URL as the ADF holds it, whatever its scheme (docs/decisions.md §HTML writes a URL as the ADF holds it, whatever its scheme).

The carry element

A node the sections above cannot write where it stands is the carry element: <div> in block position, <span> inline, of class adf-carry, holding the node's JSON in data-adf and showing the node's text. A carry element may hold a node the sections above write, as the markdown carry may: it reads back as the node it holds, so HTML stored while a node rode the carry reads the same once a later release writes it as its own element.

<div class="adf-carry" data-adf="{&quot;attrs&quot;:{&quot;panelType&quot;:&quot;info&quot;},…,&quot;type&quot;:&quot;panel&quot;}">Check the collation.</div>
<p>Ask <span class="adf-carry" data-adf="{&quot;attrs&quot;:{&quot;id&quot;:&quot;5b10a2&quot;,&quot;text&quot;:&quot;@Mikael&quot;},&quot;type&quot;:&quot;mention&quot;}">@Mikael</span></p>

• data-adf holds the node's JSON compact, keys sorted, as !adf:carry does in markdown, its type included. A document holding no content key is the block carry of {"type":"doc","version":1}.
• The text shown is every text node's text below the node, and what a node holding no text shows in its place: a mention's text, else @ and its id; an emoji's text, else its shortName; a status's text; a date as 2026-09-13 in UTC; a card's URL, else its name, else the URL its data holds; media's alt, else an external one's URL; an extension's text; an expand's title. A line feed parts two blocks and stands for a hard break. Null characters are dropped.
• A node rides the carry where it holds an attribute, mark or key its element does not write, an empty attrs, content or marks, or a value its element cannot hold:
  • text holding no character, or a null character, which HTML cannot hold; text holding a mark twice, or a mark with attributes besides a link's href and title;
  • an unmarked text node straight after another, which would read back as one;
  • a link whose href or title holds a null character, and an image whose url or alt holds one or whose link's href or title does;
  • a code block holding more than one text node, a marked one, or a language holding whitespace or a null character;
  • a list holding a node that is no listItem, or an item holding attributes or marks: the whole list rides the carry;
  • a listItem outside a list, an inline node in block position and a block node inline.
• A block carry's JSON nests at most 500 levels less the depth it stands at, an inline carry's at most 500, as in markdown.