# 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` | `
`, a line feed, its blocks, a line feed, `
` | | `bulletList` | `` | | `codeBlock` | `
…
`, 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` | | `heading`, `level` 1 to 6 | `

…

` to `
…
` | | `listItem` | its first paragraph straight after `
  • `: bare where it holds content and no attribute, `
  • Bolt
  • `, and as its `

    ` element where it holds an attribute, `

  • Bolt

  • `; where other blocks follow, each after a line feed, and a line feed before ``. Where the first block is no paragraph, holds neither content nor an attribute, or rides the carry: `
  • `, a line feed, its blocks, a line feed, `
  • ` | | `decisionList` | ``; each `decisionItem` is `
  • ` around its inline content | | `expand`, `nestedExpand` | `
    `, `
    `, a line feed, a `` holding the `title` where there is one, its blocks, each after a line feed, a line feed, `
    ` | | `mediaGroup` | `
    ` holding a `` for each `media`, none between | | `mediaSingle`, centered, holding one external `media` | `

    …

    `, no `alt` where the media holds none; `

    ` where a link marks it | | `mediaSingle`, any other | `
    `, its `media` as the `` below, then its caption as `
    …
    `, on one line, `
    `; the `` inside `` where a link marks the media | | `orderedList` | as `bulletList` with `
      `; `
        ` for an `order` of 3, a safe integer other than `-0`; no `start` where the list holds no `order` | | `panel` | `
        `, a line feed, its blocks a line each, a line feed, `
        ` | | `paragraph` | `

        …

        `; `

        ` for an `alignment` mark of `center` and `text-align:right` for `end`, as on a heading | | `rule` | `


        ` | | `taskList` | `
          `, a line feed, its items a line each, a line feed, `
        `; each `taskItem` is `
      1. `, a space, then its inline content, the checkbox `checked=""` as well where `state` is `DONE`, and the space left out where it holds none | | `table` | ``, a line feed, its sections parted by a line feed, a line feed, `
        `: a `` where its first row holds cells that are all `tableHeader`, and a `` 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` | ``, ``, each holding its blocks as a `listItem` does: `Bolt M8`; attributes `colspan`, `rowspan`, `style="background-color:#fffae6"` for `background`, and `data-colwidth="120,80"` for `colwidth`, first and in that order | | `tableRow` | ``, its cells with no line feed between them, `` | A container holding no `content` key is its element holding nothing: `
        `, `
          `, `
        • `, `
          `, ``, ``, `
          `, `
          `; so is a paragraph or heading, `

          `. A media is `…`: `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 `` with no `src`. Its `type` is a `data-*` attribute, left out where the media is external and holds a `url`. A `
          ` holds the escaped `title`, `` 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. ```html
          PartStockBin
          Bolt M8Low
          12A4
          ``` 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, media group or the media they hold, 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 ``'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: `
            `, `
            `. A code
            block's `data-*` attributes stand on its `
            `.
            
            ## Inline
            
            | ADF | HTML |
            | --- | --- |
            | `date` | ``, the day in UTC |
            | `backgroundColor`, `textColor` | ``, `` around the text; the colour a `#` and letters and digits, or letters and digits alone |
            | `code`, `em`, `strike`, `strong`, `underline` | ``, ``, ``, ``, `` around the text |
            | `emoji` | `🎉`, its `text` the content |
            | `hardBreak` | `
            ` | | `inlineCard`, holding a `url` | `
            https://example.com/spec` | | `inlineCard`, holding `data` and no `url` | `Release plan`, `href` the URL its `data` holds and the text its name, else that URL | | `link`, holding `href` and an optional `title` | `` around the text | | `mention` | `@Mikael`, its `text` the content | | `status` | `In review`, its `text` the content | | `subsup` | `` or `` 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: `manual`. Each text node writes its own elements, so two text nodes a link marks are two `` elements. ## Escaping Text and attribute values escape `&`, `<`, `>` and `"` as `&`, `<`, `>` and `"`. 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: `
            ` in block position, `` 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. ```html

            Read the CommonMark spec first.

            Then import.

            Ask @5b10a2

            ``` - `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 `
            `, each block's content is a `

            `, and a code block's is `

            …
            `, keeping its line feeds and spaces. The `` 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 ``, a `
            ` parts each block's content from the next. - A hard break is `
            `, and so is a line feed in text outside a `
            `'s code block. - Text a link marks is `` 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: `The moon (image)`. - A node referencing what it cannot show is a note naming it, `(image)`: `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: `(image)`. - 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, or a mark with attributes besides a link's `href` and `title`; - 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; - an image holding an attribute besides its `center` layout and its media's `type`, `url` and non-empty `alt`; - 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, 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 | | --- | --- | | `"` in text | a raw `"` | | a no-break space | ` ` | | `<` and `>` in an attribute value | a raw `<` and `>`, as older browsers write them | | a line feed | `\r\n` | 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 `

            `, 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`.