3
0
mirror of https://github.com/larvit/adf-codec.git synced 2026-11-18 22:25:44 +01:00
Files
adf-codec/spec/html.md
T

17 KiB

The HTML dialect

The HTML adfToHtml writes and htmlToAdf reads: 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

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
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>
codeBlock <pre><code class="language-js">…</code></pre>, the language one token holding no ASCII whitespace (a tab, line feed, form feed, carriage return or space); no class where it holds no language
decisionList <ul class="adf-decision-list">, a line feed, its items a line each, a line feed, </ul>; each decisionItem is <li class="adf-decision" data-state="DECIDED"> around its inline content
expand, nestedExpand <details class="adf-expand">, <details class="adf-nested-expand">, a line feed, a <summary> holding the title where there is one, its blocks, each after a line feed, a line feed, </details>
heading, level 1 to 6 <h1>…</h1> to <h6>…</h6>; the alignment and indentation marks as on a paragraph
listItem its first paragraph straight after <li>: bare where it holds content and no attribute, <li>Bolt</li>, and as its <p> element where it holds an attribute, <li><p data-local-id="p1">Bolt</p></li>; where other blocks follow, each after a line feed, and a line feed before </li>. Where the first block is no paragraph, holds neither content nor an attribute, or rides the carry: <li>, a line feed, its blocks, a line feed, </li>
mediaGroup <div class="adf-media-group"> holding a <span class="adf-file" data-id="…" data-type="file"></span> for each media, none between
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
mediaSingle, any other <figure class="adf-media-single" data-layout="wide">, its media as the <img> below, then its caption as <figcaption>…</figcaption>, on one line, </figure>; the <img> inside <a href="…"> where a link marks the media
orderedList as bulletList with <ol>; <ol start="3"> for an order of 3, a safe integer other than -0; no start where the list holds no order
panel <div class="adf-panel" data-panel-type="info">, a line feed, its blocks a line each, a line feed, </div>
paragraph <p>…</p>; <p style="text-align:center"> for an alignment mark of center and text-align:right for end, <p data-indent-level="2"> for an indentation mark of level 2, as on a heading
rule <hr>
table <table>, a line feed, its sections parted by a line feed, a line feed, </table>: a <thead> where its first row holds cells that are all tableHeader, and a <tbody> for the other rows where there are any. Each section is its tag, a line feed, its rows a line each, a line feed, its closing tag
tableCell, tableHeader <td>, <th>, each holding its blocks as a listItem does: <td>Bolt M8</td>; attributes colspan, rowspan, style="background-color:#fffae6" for background, and data-colwidth="120,80" for colwidth, first and in that order
tableRow <tr>, its cells with no line feed between them, </tr>
taskList <ul class="adf-task-list">, a line feed, its items a line each, a line feed, </ul>; each taskItem is <li class="adf-task" data-state="TODO"><input type="checkbox" disabled="">, a space, then its inline content, the checkbox checked="" as well where state is DONE, and the space left out where it holds none

A container holding no content key is its element holding nothing: <blockquote></blockquote>, <ul></ul>, <li></li>, <table></table>, <tr></tr>, <td></td>, <div class="adf-panel"></div>, <details class="adf-expand"></details>; so is a paragraph or heading, <p></p>.

A media is <img src="…" alt="…" height="…" width="…">: src its url, each other attribute left out where the media holds none, height and width a positive safe integer each. A media holding no url is <img class="adf-media"> with no src. Its type is a data-* attribute, left out where the media is external and holds a url.

A <summary> holds the escaped title, <summary></summary> for an empty one, and an expand with no title has none. panelType is data-panel-type, and a task item's or decision item's state is data-state, among the other attributes below.

<table>
<thead>
<tr><th>Part</th><th>Stock</th><th>Bin</th></tr>
</thead>
<tbody>
<tr><td rowspan="2">Bolt M8</td><td colspan="2" style="background-color:#fffae6" data-colwidth="120,80">Low</td></tr>
<tr><td>12</td><td>A4</td></tr>
</tbody>
</table>

A table and each of its rows count one nesting level; a cell doesn't count, nor does a list item.

On a paragraph, heading, quote, list, list item, table, row, cell, code block, rule, panel, expand, task or decision list or item, media single, caption or media, each attribute its type holds (spec/flavour.md §Block nodes) that the element does not write as level, order, language, colspan, rowspan, background, colwidth, an expand's title, or an <img>'s alt, height, url and width is a data-* attribute, named as HTML's dataset names it, localId as data-local-id, after the element's own attributes and sorted by name. A string is its value; any other value is its JSON, compact: <ol start="3" data-local-id="91177a27-b0ff">, <pre data-wrap="true"><code>. A code block's data-* attributes stand on its <pre>.

Inline

ADF HTML
backgroundColor, textColor <mark style="background-color:#fffae6">, <span style="color:#bf2600"> around the text; the colour a # and letters and digits, or letters and digits alone
code, em, strike, strong, underline <code>, <em>, <del>, <strong>, <u> around the text
date <time class="adf-date" datetime="2025-08-25" data-timestamp="1756080000000">2025-08-25</time>, the day in UTC
emoji <span class="adf-emoji" data-id="1f389" data-short-name=":tada:">🎉</span>, its text the content
hardBreak <br>
inlineCard, holding a url <a class="adf-inline-card" href="https://example.com/spec">https://example.com/spec</a>
inlineCard, holding data and no url <a class="adf-inline-card" href="https://example.com/plan" data-data="{&quot;name&quot;:&quot;Release plan&quot;,&quot;url&quot;:&quot;https://example.com/plan&quot;}">Release plan</a>, href the URL its data holds and the text its name, else that URL
link, holding href and an optional title <a href="…" title="…"> around the text
mention <span class="adf-mention" data-access-level="CONTAINER" data-id="5b10a2" data-user-type="DEFAULT">@Mikael</span>, its text the content
status <span class="adf-status" data-color="yellow">In review</span>, its text the content
subsup <sub> or <sup> around the text, for a type of sub or sup
text its text, escaped

A date, emoji, inlineCard, mention or status writes each other attribute its type holds as a data-* attribute, named and sorted as on a block, data-local-id among them.

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 &amp;, &lt;, &gt; and &quot;. Attribute values are double-quoted. Every URL is written as the ADF holds it, whatever its scheme (docs/decisions.md §HTML writes a URL as the ADF holds it, whatever its scheme): a link's href, an image's src, a card's href, and the href of each link a carry element shows.

HTML text and attribute values cannot hold these (WHATWG HTML §13.1.3): any control but a tab, line feed or form feed, so a carriage return too, which a parser reads as a line feed; a noncharacter; and a lone surrogate, which UTF-8 cannot encode. A node holding one in a value its element writes rides the carry.

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 its content. 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;extensionKey&quot;:&quot;toc&quot;},…,&quot;type&quot;:&quot;bodiedExtension&quot;}"><p>Read the <a href="https://spec.commonmark.org/">CommonMark spec</a> first.</p><p>Then import.</p></div>
<p>Ask <span class="adf-carry" data-adf="{&quot;attrs&quot;:{&quot;id&quot;:&quot;5b10a2&quot;},&quot;type&quot;:&quot;mention&quot;}">@5b10a2</span></p>
  • data-adf holds the node's JSON compact, keys sorted, as !adf:carry does in markdown, its type included, each character HTML cannot hold spelled as a JSON escape, \u0085. A document holding no content key is the block carry of {"type":"doc","version":1}.
  • The content 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 where it has one; 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.
    • In a <div>, each block's content is a <p>, and a code block's is <pre><code class="language-js">…</code></pre>, keeping its line feeds and spaces. The <code> takes the class the code block's own element takes, and none where the language is not one token free of ASCII whitespace. In a <span>, a <br> parts each block's content from the next.
    • A hard break is <br>, and so is a line feed in text outside a <div>'s code block.
    • Text a link marks is <a href="…" title="…"> around it, or the text alone where HTML cannot hold the link's href or title; a title that is no string is left out. A card is a link to its URL.
    • An external image with no link to another target is a link to its URL. An image marked by a link to another target shows as portable markdown writes it inline. First comes the link, around the image's alt, else the link's target, else the image's URL. Then comes (image), the word image linking to the image: <a href="https://example.com/">The moon</a> (<a href="https://example.com/moon.jpg">image</a>).
    • A node referencing what it cannot show is a note naming it, <em>(image)</em>: image for media with no alt or URL, link card for a card with neither URL nor name, an extension's key, else extension, for an extension with no text, and synced block for a syncBlock. A link marking the node goes around the note: <a href="…"><em>(image)</em></a>.
    • Characters HTML cannot hold are dropped.
  • A node rides the carry where it holds a mark or a key its element does not write, an attribute its type does not hold as that kind, an empty attrs, content or marks, or a value its element cannot hold:
    • text holding no character, or a character HTML cannot hold; text holding a mark twice, a link with attributes besides href and title, or a mark with an attribute its element does not write;
    • an unmarked text node straight after one written as plain text, which would read back as one;
    • a link whose href or title holds a character HTML cannot hold, and an image whose url or alt holds one or whose link's href or title does;
    • a heading whose level is not 1 to 6, and an ordered list whose order is not a safe integer or is -0;
    • an emoji, mention or status with no text, and a date whose timestamp names no day from year 1 to 9999;
    • a card holding an empty url, both a url and data, or neither, and one holding data alone whose url is missing or holds only whitespace;
    • a code block holding more than one text node, a marked one, or a language holding ASCII whitespace;
    • a hard break holding an attribute;
    • a mediaSingle holding anything but one media, then at most one caption, or a mediaGroup holding anything but media; a media holding more than one mark, a mark that is no link, or a height or width that is not a positive safe integer;
    • a paragraph or heading holding a mark besides one center or end alignment or one indentation of level 1 to 6;
    • a textColor or backgroundColor whose color is not letters and digits after an optional #;
    • a panel or expand holding an attribute its type does not hold as that kind; a taskItem whose state is not DONE or TODO, or a task or decision list holding a node that is no item of its own kind, blockTaskItem included: the whole list rides the carry;
    • a list holding a node that is no listItem, or an item holding a mark, an empty key or an attribute its type does not hold: the whole list rides the carry;
    • a table holding a node that is no tableRow, a row holding a node that is no cell, or a table, row or cell holding a mark, an empty key or an attribute its type does not hold: the whole table rides the carry. So does a cell whose colspan or rowspan isn't a positive safe integer, whose colwidth isn't a list of numbers, or whose background isn't a string of one or more letters and digits, after an optional #;
    • a listItem, tableRow or cell outside its parent, an inline node in block position and a block node inline.
  • An inline card a link marks, a known block holding text, a known non-text inline node holding text or non-empty content, and a known block that takes no content, such as rule, holding non-empty content are refused as unsupported-node-shape, carried or not, by adfToHtml and by htmlToAdf reading a carry element, since Atlassian's schema allows none of these.
  • 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.

Reading

htmlToAdf reads the HTML above, so htmlToAdf(adfToHtml(doc)) deep-equals doc. Wherever the HTML above holds a spelling in the table's left column, htmlToAdf also reads the right one, as a browser serializes HTML (WHATWG HTML §13.3) or a form post sends it, in a carry element's data-adf and in what it shows too:

The HTML above writes Also read
&quot; in text a raw "
a no-break space &nbsp;
&lt; and &gt; in an attribute value a raw < and >, as older browsers write them
a line feed \r\n
an expand's <details> the same with open="" after its other attributes, the state of a <details> its user opened, dropped

A refusal's position counts the HTML as handed in. htmlToAdf reads a carry element's node from its data-adf, and what the element shows, through its closing tag, must be what adfToHtml shows for that node in either spelling: an edit there would be lost, so it is unmappable-html.

  • Any other HTML is unmappable-html: another element, attribute or escape, attributes in another order, a block on the line of another, a carriage return not followed by a line feed, or non-empty HTML not ending in a line feed.
  • An emoji, mention, status, date or card element with empty text, a date whose datetime or text is not the day its data-timestamp names, a card without data-data whose href and text are not one URL, and a card with data-data whose href is not the URL its data holds or whose text is not its name, else that URL, are unmappable-html.
  • A task item whose checkbox is checked where its data-state is TODO, or not where it is DONE, and one whose data-state is neither, are unmappable-html.
  • A data-* attribute that its element does not take, such as data-level on <h1>, or that holds a value outside its attribute's kind or not written as compact JSON, is unsupported-node-shape.
  • A carry element's data-adf holding invalid JSON is unmappable-html. JSON that is no ADF node, is not compact with its keys sorted, or holds a number JSON cannot spell is unsupported-node-shape, and so is the document's own carry element beside another block.
  • Blocks nest at most 500 levels, and a carried node's JSON at most as many as its position leaves, as in writing; past that is unsupported-nesting-depth.