` | | `bulletList`, `orderedList`, `listItem` | ``, `
`, `
` for an `order` of 3, and `
- `; an item's first paragraph stands bare, `
- Bolt
`, or as `- ` where it holds an attribute | | `codeBlock` | `
Bolt
`, no `class` without a language | | `date`, `emoji`, `mention`, `status` | ``, `🎉`, `@Mikael`, `In review` | | `hardBreak` | `
` | | `heading` | `` to `
` | | `inlineCard` holding a `url`, or `data` and no `url` | `…`; for `data`, `href` is the URL `data` holds, the text its name, else that URL, and `data-data` the whole `data` as JSON | | `link` | `` | | `mediaSingle` holding an external `media`, centered, uncaptioned, holding no other attribute such as `width` or `localId` | `
`, the image inside `` where a link marks it; an image holding such an attribute, as editor-written ones do, rides the carry element | | `paragraph` | `
` | | `rule` | `
` | | `table`, `tableRow`, `tableCell`, `tableHeader` | ``, `` for a first row of `tableHeader` cells alone, ``, `
`, ` ` and ` `; a cell's first paragraph stands as an item's does, and ` ` writes its attributes | | `text` marked `code`, `em`, `strong` | ` `, ``, ``, the first mark outermost | | an attribute its type holds that its element does not write, such as `localId`, on a paragraph, heading, quote, list, list item, table, row, cell, code block, rule, emoji, mention, status, date or card | `data-*` named as HTML's `dataset` names it: `` | | any other node, or a node holding what its element cannot, except a shape Atlassian's schema forbids, which is refused ([The errors](#the-errors)) | `
`, a `` inline | - Every URL is written as the ADF holds it, `javascript:` included: a link's, an image's, a card's, and a carried link's in the carry element. Sanitize the HTML before showing a document from an author you do not trust. - Text and attribute values are escaped: `&`, `<`, `>` and `"`. A node holding what HTML cannot hold, such as a carriage return or a control character, rides the carry element. - In a `its content
`, the carry element shows each block's content as a ``, and a code block's as `
` keeping its indentation; in a ``, it parts blocks with `
`. It shows text a link marks as a link, a status or emoji by its text, a mention by its text, else `@` and its id, a date as `2026-09-13` in UTC, a card as a link to its URL, an external image as a link to it, a stored one by its `alt`, and an expand by its title. An image marked by a link to another target shows that link, then `(image)` linking to the image. A node it cannot show leaves a note instead, such as `(image)`; a link marking the node goes around the note. `htmlToAdf` reads that HTML back. It reads a carry element's node from its `data-adf`, and what the element shows must be what `adfToHtml` shows for that node: an edit there would be lost, so it is refused. It reads the HTML as a browser's `innerHTML` writes it too, and as a form post sends it: a raw `"` in text, ` ` for a no-break space, a raw `<` or `>` in an attribute value, and `\r\n` for a line feed. Other HTML is refused as `unmappable-html`: another element, attribute or escape, such as ``, `
` or `'`, a lone `\r`, and HTML missing its final line feed. A few causes, such as a `data-*` attribute its element does not take, are `unsupported-node-shape` instead, and nesting past 500 levels is `unsupported-nesting-depth`. [Either direction](#either-direction) lists every cause of both. ## The errors Serves [Goals](#goals) 1. An ADF node type this version does not know is not an error: the lossless pair carries it opaquely and restores it unchanged ([Unknown nodes ride the carry](https://github.com/larvit/adf-codec/blob/main/docs/decisions.md#unknown-nodes-ride-the-carry)). ### The error shape `ConvertError` is `{ code, message, path, position? }`. - `code` is from the exported closed list `ConvertErrorCode`, safe to `switch` on exhaustively with no `default`. Before 1.0 the list changes only in a minor release; from 1.0 only in a major release. - `message` is free text for a person fixing the input. It may change in any release. - `path` is the node's place from the document root, alternating `'content'` and an index, so `path.map((step) => '/' + step).join('')` is a JSON Pointer at the node, or at the list holding it where `adfToPortableMarkdown` unwraps a list into its items. The empty path is the document itself. - `position` is `{ line, offset }` into the string passed in: `line` counted from 1, `offset` a UTF-16 code unit, which is a JavaScript string index. It points at or before the refusal — currently the start of the line the enclosing block begins on in markdown, and of the line the refusal stands on in HTML; a later minor may narrow that, never widen it. For `not-a-string` it is `{ line: 1, offset: 0 }`. A parse always names a position, so the three markdown readers and `htmlToAdf` return `ParseError`, whose `position` reads without a guard. An emit reads no source and carries `path` alone. One handler typed on `ConvertError` takes both. A call reports the first refusal in document order and stops, so a document with several surfaces them one per call. Every refusal but `engine-limit` is deterministic — there is no I/O anywhere — so a retry returns the identical error: fix the input, or set the document aside. `engine-limit` can mean memory ran short: retry it once, and treat a repeat as lasting. Only an out-of-memory throw the call can catch becomes `engine-limit`: on V8 (Node, Deno, Chrome), running out of JavaScript heap ends the process. Convert input of unbounded size in a separate process with its own memory limit where that must not take yours down. ### Parsing Which reader raises which code: [The calls](#the-calls). Codes every direction raises: [Either direction](#either-direction). | Code | Fires when | What you can do | | --- | --- | --- | | `malformed-directive` | an `!adf:` the grammar cannot read — a prefix completing no directive, an unclosed container, `[content]` or `{attrs}`, a closer with no container of its name open, a leaf given a body, `{attrs}` out of order or duplicated, invalid JSON in an opaque carry | write the spelling the message names, or keep it literal: escape the prefix — `\!adf:`, block and inline alike — or, for a code fence whose info string opens `adf:`, drop the info string and wrap the fence in `!adf:codeBlock {language="adf:…"}` | | `malformed-pipe-table` | a pipe row that is no pipe table — a missing `---` delimiter row, or a delimiter or body row whose cell count differs from the header's; in `losslessMarkdownToAdf` also an alignment colon, and a header or delimiter row not opening with a pipe | add a `---` row under the header and give every row the header's cell count; for `losslessMarkdownToAdf`, also open every row with a pipe and drop the colons. To keep the lines literal text, escape the leading pipe of every one — escaping a single row leaves the next to open a fresh table and fail the same way — or, for a table without leading pipes, write one `\|` of its delimiter row as `\\|` | | `not-a-string` | the value handed in is not a string, such as `null`, a number or a `String` object | pass the input as a string, `String(value)` for a `String` object; the message names the value's type | | `unknown-directive-name` | a directive whose name is no node or mark this version spells | check the name in [`spec/flavour.md`](https://github.com/larvit/adf-codec/blob/main/spec/flavour.md), or escape the prefix as `\!adf:`; the spelling itself is well formed, so a later minor may give the name meaning | | `unmappable-html` | the markdown holds raw HTML, a comment and a processing instruction among them; the HTML handed to `htmlToAdf` holds HTML `adfToHtml` does not write, in a browser's spelling or its own, such as an edit to what a carry element shows, unless a code under [Either direction](#either-direction) names the cause | remove the construct, or write what it holds as markdown; for `htmlToAdf`, write the HTML as [`spec/html.md`](https://github.com/larvit/adf-codec/blob/main/spec/html.md) spells it | ### Emitting `adfToLosslessMarkdown`, `adfToPortableMarkdown` and `adfToHtml` raise these, and the codes under [Either direction](#either-direction): | Code | Fires when | What you can do | | --- | --- | --- | | `not-an-adf-document` | the value handed in is no ADF document — a missing or wrong `type`, a stray key, a node that is not a node, an object in the document holding itself, an attribute value that is not a plain object, array or JSON primitive, such as a `Date` or `Map` | guard the boundary you receive JSON at with `isAdfDocument`; the message names the branch that refused. Build an attribute value as JSON holds it: `date.toISOString()`, `Object.fromEntries(map)`, `{ ...instance }` | | `unsupported-document-version` | the document's `version` is not 1 | keep the ADF and pass the document over, or show it read-only; the version is the site's, not yours to change | ### Either direction Every call can raise these: | Code | Fires when | What you can do | | --- | --- | --- | | `engine-limit` | in every call: a conversion that passes the longest array, `Map` or `Set` the JavaScript engine builds, or that the engine reports as out of memory; on JavaScriptCore (Bun, Safari), also one that passes its longest string, 2^31 − 1 characters | retry once; if it repeats, writing: set the document aside, keeping the ADF and passing it over or showing it read-only; reading: shorten the input, or nest its lists and quotes less deeply | | `unsupported-nesting-depth` | blocks, marks, an attribute's JSON or a carried node's JSON nest past 500 levels | keep the ADF and pass the document over, or show it read-only; flatten the input where you are the one who wrote it | | `unsupported-node-shape` | each cause listed below the table | the remedy beside each cause below | - **Reading, in `losslessMarkdownToAdf`.** Fix what the message names; [`spec/flavour.md`](https://github.com/larvit/adf-codec/blob/main/spec/flavour.md) lists every type's attributes and body. The markdown: - spells a node with an attribute, value, argument or body its type does not take, or without one it needs; - puts a line ending or a null character in an `emoji`, `mention` or `status` content slot: replace a line ending with a space, or, for either, write the node as `!adf:carry`; - wraps a directive mark around nothing, or only around nodes that take no such mark, such as a hard break, a mention, a code span or, for `border`, text; - writes a link whose text holds something besides hard breaks, but no node that takes a link, such as `[!adf:status[Done]{color=green}](/u)`: write the link around text beside them; - writes as a directive a node or mark the lossless flavour spells as CommonMark; - puts `!adf:textBreak{}` where it parts nothing, or `!adf:doc` anywhere but as the whole document; - carries a node the writers' cause below names, such as an inline card a link marks. - **Reading, in `htmlToAdf`.** Fix what the message names; [`spec/html.md`](https://github.com/larvit/adf-codec/blob/main/spec/html.md) lists each element's attributes. The HTML: - holds a `data-*` attribute its element does not take, such as `data-level` on ``, or one holding a value outside its attribute's kind or not written as compact JSON, such as `data-wrap="yes"`; - holds a carry element whose `data-adf` holds JSON that is no ADF node, is not written compact with its keys sorted, or holds a number JSON cannot spell; - holds a carry element carrying a node the writers' cause below names, such as an inline card a link marks; - holds the document's own carry element beside another block. - **Writing, in `adfToLosslessMarkdown`**: a node not riding the carry that carries one mark type twice. Keep the ADF and show the document read-only; where you built the ADF, fix what the message names. - **Writing, in `adfToHtml`, `adfToLosslessMarkdown` and `adfToPortableMarkdown`**: a shape Atlassian's schema forbids, even inside a node that rides the carry: an inline card a link marks, a known block holding `text`, a known non-text inline node holding `text` or non-empty `content`, or a known block that takes no content, such as `rule`, holding non-empty `content`. Keep the ADF and pass the document over or show it read-only; where you built the ADF, remove what the error's `path` and message name. - **Writing, in `adfToPortableMarkdown`**: a line or task list the portable writer cannot spell. This is a bug in this library: report it. - **Past the engine's longest string**: - a writer's markdown or HTML would pass 536870888 characters, V8's longest string, on every engine; - in `adfToPortableMarkdown`, the document's text alone would, edge whitespace included; - in `losslessMarkdownToAdf`, a directive's plain CommonMark would; - in every call, a conversion passes V8's or SpiderMonkey's longest string. When writing, set the document aside: keep the ADF, and pass it over or show it read-only. When reading, shorten the input, or nest its lists and quotes less deeply. ## The guarantees Serves [Goals](#goals) 1, 4 and 5. - `losslessMarkdownToAdf(adfToLosslessMarkdown(doc))` deep-equals `doc` as JSON, for a document of plain objects as `JSON.parse` builds them — every key and value as `doc` holds it, adjacent text nodes, an empty `attrs`, `content` or `marks` and `-0` included, and unknown node types carried opaquely ([Unknown nodes ride the carry](https://github.com/larvit/adf-codec/blob/main/docs/decisions.md#unknown-nodes-ride-the-carry)). - `htmlToAdf(adfToHtml(doc))` deep-equals `doc` on the same terms. - Markdown this library reads, and markdown it writes, means what the CommonMark spec says. The bullets below name every exception. - CommonMark is valid input to `commonMarkToAdf`, apart from the raw HTML `unmappable-html` names, nesting past 500 levels, and input whose conversion passes the engine's longest string, refused as `unsupported-node-shape`, or another engine limit, refused as `engine-limit`. - The other readers claim shapes CommonMark reads as text or code. `losslessMarkdownToAdf` claims four: literal text matching directive, pipe-table or strikethrough syntax, and a code fence whose info string opens `adf:`. `portableMarkdownToAdf` claims what [Portable markdown](#portable-markdown) lists. A claimed shape that does not complete, such as a pipe row without a delimiter row, is an error result; each can be kept literal ([`spec/flavour.md`](https://github.com/larvit/adf-codec/blob/main/spec/flavour.md)). - A document any reader built, written back with `adfToLosslessMarkdown`, takes the library's canonical spelling, which round-trips byte-identically. - These CommonMark spellings parse without an error but build a document the reference implementation renders differently, because ADF holds no node for what the reference renders: - An empty link text reads as its destination, `[](/url)` as `/url` linked to `/url`, and `[]()` as nothing. A link text holding only hard breaks reads the same, followed by its hard breaks. - An image reads as an image only alone in its paragraph. Anywhere else — beside other text, in a heading or a table cell, or in the paragraph a task marker opens — it reads as its alt text linked to its URL: `See .` reads as `See [the moon](moon.png).`. To keep an image an image, give it a paragraph of its own: a blank line between it and any other line. - A code span inside emphasis reads as code without the emphasis, since ADF gives code text no mark but a link or an annotation: ``**`npm ci`**`` reads as `` `npm ci` ``. - Inside a link, an image reads as plain text the link marks. After the link comes `(image)`, which links to the image: `[look at  tonight](/moon)` reads as `[look at the moon tonight](/moon) ([image](moon.png))`. A link to the image's own URL takes no `(image)`, unless the image's title is one the link lacks. A link alone in its paragraph whose whole text is one image reads as that image, with the link marking it. - An image's title becomes its caption when the image stays an image, and otherwise the title of the link to the image. And these, for other reasons: a shortcut reference matching its definition only under Unicode case folding stays unresolved, and a link whose text holds an autolink keeps the inner link and leaves the outer brackets literal text, which the spec requires and the reference itself breaks, nesting one `` in the other. - Not every document converts back: `adfToLosslessMarkdown` refuses a document nesting past 500 levels, a document meeting an `unsupported-node-shape` cause listed for it, for a writer or for every call, and a conversion `engine-limit` stops. Show the refusal and keep the document read-only; saving markdown you could not produce is the loss the round-trip exists to stop. - Both readers narrow GFM's pipe table. A body row whose cell count differs from the header's is an error result, where GFM pads or cuts it. A line holding no `|` ends the table, where GFM reads it as a row. - `losslessMarkdownToAdf` also needs a leading `|`: a header or delimiter row without one is an error result, and a later line without one ends the table. It refuses an alignment colon in the delimiter row too, since ADF holds no column alignment. `portableMarkdownToAdf` accepts both and drops the alignment. The trailing pipe is canonical output, optional in input. - Past that and `~~`, `losslessMarkdownToAdf` reads no GFM: an autolink literal and a `- [ ]` marker stay text, and a checklist is the `taskList` directive — `portableMarkdownToAdf` turns the marker into a `taskList`. - A document nested deeper than 500 levels is an error result, not a stack overflow, and no call loops forever on a string, or on a value `JSON.parse` or `structuredClone` builds. - The emitted formats are semver surface ([The formats are API](https://github.com/larvit/adf-codec/blob/main/docs/decisions.md#the-formats-are-api)). ## The package Serves [Goals](#goals) 8. | Aspect | Contract | | --- | --- | | Dependencies | none at runtime | | Engines | any ES2022 engine; `engines.node` is `>=18`. The test suite runs under Node, Deno and Bun, and a headless Firefox converts the corpus through the built entrypoint | | Host APIs | none: pure ECMAScript, no DOM, no `node:` import | | Module format | ESM only, one entrypoint | | Registry | public npm, `@larvit/adf-codec` | | Types | built JavaScript with `.d.ts` beside it | Contract: [`docs/decisions.md`](https://github.com/larvit/adf-codec/blob/main/docs/decisions.md#any-es2022-engine), §Any ES2022 engine to §Public on npm. ## Everything exported | Export | Kind | What it is ([The calls](#the-calls)) | | --- | --- | --- | | `AdfAttributes` | type | a node's or mark's attributes | | `AdfDocument` | type | an ADF document | | `AdfMark` | type | an ADF mark | | `AdfNode` | type | an ADF node | | `ConvertError` | type | the error a failed call returns | | `ConvertErrorCode` | type | the closed list of codes in [The errors](#the-errors) | | `ConvertErrorPath` | type | an error's place in the document | | `JsonValue` | type | an attribute value | | `ParseError` | type | the error a markdown reader or `htmlToAdf` returns, its `position` always set | | `Result` | type | every call's return value | | `SourcePosition` | type | an error's place in the markdown or HTML read | | `adfToHtml` | function | ADF to HTML | | `adfToLosslessMarkdown` | function | ADF to the lossless flavour | | `adfToPortableMarkdown` | function | ADF to portable markdown, lossy | | `commonMarkToAdf` | function | strict CommonMark to ADF | | `htmlToAdf` | function | `adfToHtml`'s HTML, read back to ADF | | `isAdfDocument` | function | type guard for `AdfDocument` | | `losslessMarkdownToAdf` | function | the lossless flavour to ADF | | `portableMarkdownToAdf` | function | portable markdown to ADF | ## Changing the source All three commands need only Docker, git and bash 5. - `./ci.sh` runs every check CI runs. - `./feature-table/write.sh` rewrites `docs/feature-table.md` from `feature-table/examples.json` and the build. `./ci.sh` fails where a change leaves that page stale. - `./mutation-tests/run.sh [
]` mutation-tests the lines changed since ` `, `origin/main` by default, in source files git tracks. It needs 6 GB of memory for Docker, and lists the mutants that survived. Survivors don't fail it; a mutant whose test run crashed does. - The README's first paragraph after the badges is the npm description: `./publish.sh` copies it to `package.json`. Keep it plain text; `./ci.sh` fails where it isn't. ## Links - [Changelog](https://github.com/larvit/adf-codec/blob/main/CHANGELOG.md) - [Upgrading](https://github.com/larvit/adf-codec/blob/main/MIGRATION.md) - [The lossless flavour's grammar, `spec/flavour.md`](https://github.com/larvit/adf-codec/blob/main/spec/flavour.md) - [Decisions](https://github.com/larvit/adf-codec/blob/main/docs/decisions.md) - [Plan](https://github.com/larvit/adf-codec/blob/main/todo.md) - [Issues](https://github.com/larvit/adf-codec/issues)