3
0
mirror of https://github.com/larvit/adf-codec.git synced 2026-11-19 06:35:44 +01:00

Ship adfToHtml: semantic HTML for the CommonMark blocks and marks, an adf-carry element for the rest

This commit is contained in:
2026-10-23 12:50:48 +02:00
committed by Lillem4n
parent 33ef8db768
commit 6fe36d5947
33 changed files with 826 additions and 147 deletions
+56 -7
View File
@@ -1,9 +1,9 @@
# @larvit/adf-codec — ADF to markdown, markdown to ADF
# @larvit/adf-codec — ADF to markdown and HTML, markdown to ADF
[![npm](https://img.shields.io/npm/v/@larvit/adf-codec)](https://www.npmjs.com/package/@larvit/adf-codec)
[![CI](https://github.com/larvit/adf-codec/actions/workflows/ci.yml/badge.svg)](https://github.com/larvit/adf-codec/actions/workflows/ci.yml)
Convert Atlassian Document Format (ADF), the rich text of Jira and Confluence, to and from markdown, with a lossless round-trip.
Convert Atlassian Document Format (ADF), the rich text of Jira and Confluence, to and from markdown, with a lossless round-trip, and to HTML.
For application developers whose app shows, edits, exports or generates the rich text Atlassian
products store as ADF.
@@ -19,6 +19,9 @@ products store as ADF.
and Obsidian render — GitHub Flavored Markdown's alerts, task lists and pipe tables, Obsidian
Flavored Markdown's callouts and highlights. It keeps the text, images by URL and link targets and
drops the rest.
- **HTML out:** `adfToHtml` writes paragraphs, headings, lists, quotes, code blocks, images and
links as their HTML elements, and every other node as an element holding its JSON and showing its
text.
- **No throws:** every call returns a result; a refusal carries a code from a closed list.
- **Runs anywhere:** pure functions with no runtime dependencies, in Node, Deno, Bun and browsers.
TypeScript types ship beside the JavaScript.
@@ -67,6 +70,18 @@ if (portable.ok) console.log(portable.value)
// > Check the collation before importing.
```
### ADF to HTML
Full reference: [HTML](#html).
```ts
import { adfToHtml } from '@larvit/adf-codec'
const html = adfToHtml(doc) // the panel above
if (html.ok) console.log(html.value)
// <div class="adf-carry" data-adf="{&quot;attrs&quot;:{&quot;panelType&quot;:&quot;warning&quot;},…}">Check the collation before importing.</div>
```
### Markdown to ADF
Full reference: [The calls](#the-calls) and [Portable markdown](#portable-markdown).
@@ -150,6 +165,7 @@ Nothing throws. `code` is from a closed list, so a `switch` with no `default` co
- [The calls](#the-calls)
- [The lossless flavour](#the-lossless-flavour)
- [Portable markdown](#portable-markdown)
- [HTML](#html)
- [The errors](#the-errors)
- [The guarantees](#the-guarantees)
- [The package](#the-package)
@@ -217,7 +233,7 @@ same marks and link.
| Package | Converts | ADF to markdown to ADF | A node type it does not know | Formats | Direct runtime dependencies |
| --- | --- | --- | --- | --- | --- |
| `@larvit/adf-codec` | both ways | the same document | kept | markdown: lossless, portable; CommonMark in | 0 |
| `@larvit/adf-codec` | both ways | the same document | kept | markdown: lossless, portable; CommonMark in; HTML out | 0 |
| `@atlaskit/editor-markdown-transformer` 6.3.1 | markdown to ADF, through `@atlaskit/editor-json-transformer` 10.0.0; ADF to markdown throws "This is not implemented yet" | – | – | markdown | 5 |
| `adf-to-markdown` 1.0.1 | ADF to markdown | – | dropped with its text | markdown | 0 |
| `adf-to-md` 1.2.1 | ADF to markdown | – | dropped with its text, as are mentions, statuses and panels | markdown | 1 |
@@ -240,12 +256,15 @@ commonMarkToAdf(markdown: string): Result<AdfDocument, ParseError>
adfToPortableMarkdown(doc: AdfDocument): Result<string>
portableMarkdownToAdf(markdown: string): Result<AdfDocument, ParseError>
adfToHtml(doc: AdfDocument): Result<string>
```
Each call's name says which markdown it reads or writes:
Each call's name says which format it reads or writes:
| Call | Markdown | Refuses with |
| Call | Reads or writes | Refuses with |
| --- | --- | --- |
| `adfToHtml` | writes HTML: the elements [HTML](#html) lists, and an `adf-carry` element holding everything else | `engine-limit`, `not-an-adf-document`, `unsupported-document-version`, `unsupported-nesting-depth`, `unsupported-node-shape` |
| `adfToLosslessMarkdown` | writes the lossless flavour: CommonMark plus GFM's pipe tables and `~~`, with `!adf:` directives and `adf:` fences for everything else | `engine-limit`, `not-an-adf-document`, `unsupported-document-version`, `unsupported-nesting-depth`, `unsupported-node-shape` |
| `adfToPortableMarkdown` | writes markdown GitHub, GitLab and Obsidian render; drops what they cannot show, and writes no directive | `engine-limit`, `not-an-adf-document`, `unsupported-document-version`, `unsupported-nesting-depth`, `unsupported-node-shape` |
| `commonMarkToAdf` | reads strict CommonMark as its spec says: a directive, a pipe table, `~~`, `==` and an `adf:` fence read as text and code | `engine-limit`, `not-a-string`, `unmappable-html`, `unsupported-nesting-depth`, `unsupported-node-shape` |
@@ -425,6 +444,34 @@ saving what this pair read replaces mentions, attachments and macros with text.
position, the same on every read. Join markdown bound for one document and read it once: the same
markdown read twice into one document repeats its ids.
## HTML
Serves [Goals](#goals) 1, 6 and 7. `adfToHtml` writes the HTML element for each node HTML has one
for, and keeps every other node whole: an element of class `adf-carry` holds the node's JSON in
`data-adf` and shows the node's text, so a reader of the page loses no content. No stylesheet
ships. The complete dialect:
[`spec/html.md`](https://github.com/larvit/adf-codec/blob/main/spec/html.md).
| ADF | HTML |
| --- | --- |
| `blockquote` | `<blockquote>` |
| `bulletList`, `orderedList`, `listItem` | `<ul>`, `<ol>`, `<ol start="3">` for an `order` of 3, and `<li>`; an item's first paragraph stands bare, `<li>Bolt</li>` |
| `codeBlock` | `<pre><code class="language-js">`, no `class` without a language |
| `hardBreak` | `<br>` |
| `heading` | `<h1>` to `<h6>` |
| `link` | `<a href="…" title="…">` |
| `mediaSingle` holding an external `media`, centered, uncaptioned | `<p><img src="…" alt="…"></p>`, the image inside `<a>` where a link marks it |
| `paragraph` | `<p>` |
| `rule` | `<hr>` |
| `text` marked `code`, `em`, `strong` | `<code>`, `<em>`, `<strong>`, the first mark outermost |
| any other node, or a node holding what its element cannot | `<div class="adf-carry" data-adf="{…}">its text</div>`, a `<span>` inline |
- Text and attribute values are escaped: `&`, `<`, `>`, `"` and a carriage return.
- The carry element shows a mention, status or emoji by its text, a date as `2026-09-13` in UTC, a
card by its URL, an image by its `alt`, else its URL, and an expand by its title.
- A link or image whose URL a browser would run or read as a file, such as `javascript:`, rides
the carry element, so the HTML follows no such URL.
## The errors
Serves [Goals](#goals) 1. An ADF node type this version does not know is not an error: the lossless
@@ -475,7 +522,7 @@ Which reader raises which code: [The calls](#the-calls). Codes every direction r
### Emitting
`adfToLosslessMarkdown` and `adfToPortableMarkdown` raise these, and the codes under
`adfToLosslessMarkdown`, `adfToPortableMarkdown` and `adfToHtml` raise these, and the codes under
[Either direction](#either-direction):
| Code | Fires when | What you can do |
@@ -514,7 +561,8 @@ Every call can raise these:
- **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 would pass 536870888 characters, V8's longest string, on every engine;
- 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.
@@ -616,6 +664,7 @@ Contract: [`docs/decisions.md`](https://github.com/larvit/adf-codec/blob/main/do
| `ParseError` | type | the error a markdown reader returns, its `position` always set |
| `Result` | type | every call's return value |
| `SourcePosition` | type | an error's place in the markdown |
| `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 |