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:
@@ -1,9 +1,9 @@
|
||||
# @larvit/adf-codec — ADF to markdown, markdown to ADF
|
||||
# @larvit/adf-codec — ADF to markdown and HTML, markdown to ADF
|
||||
|
||||
[](https://www.npmjs.com/package/@larvit/adf-codec)
|
||||
[](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="{"attrs":{"panelType":"warning"},…}">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 |
|
||||
|
||||
Reference in New Issue
Block a user