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

List the three converters that fail ordinary input, each with where it fails

This commit is contained in:
2026-10-28 23:43:15 +01:00
committed by Lillem4n
parent bb89a1b516
commit 55968bbd26
5 changed files with 19 additions and 7 deletions
+1
View File
@@ -83,6 +83,7 @@ In `docs/decisions.md`:
- Readable spellings take the `try` prefix
- The attribute vocabulary is ADF's
- The source parts by ADF and format
- The comparison table lists every converter that starts and converts
## 1. Nothing about any consumer
+1 -1
View File
@@ -5,7 +5,7 @@
- The package's description and keywords say it needs no React, Atlaskit or runtime dependency and
runs in Node, Forge, Deno, Bun and browsers, and the README opens with the call to take for each
need. The README's first comparison table lists the npm packages running in Node that convert ADF
to or from markdown and work, wrappers and forks aside; its second table lists other ecosystems'
to or from markdown, wrappers and forks aside; its second table lists other ecosystems'
libraries and Atlassian's own paths.
- `adfToHtml` writes ADF as HTML: paragraphs, headings, lists, quotes, code blocks, rules, hard
breaks, a centered, uncaptioned external image holding no attribute but its URL and alt, and `em`,
+7 -5
View File
@@ -247,11 +247,10 @@ place, and on CI failing a change that breaks a guarantee.
## Other ADF converters
Serves [Goals](#goals) 3. The first table lists every npm package that runs in Node, converts ADF to
or from markdown and is reasonably complete and works, whatever its downloads. `markdown-to-adf`,
`md-to-adf` and `@wrtnlabs/markdown-to-adf` are left out because they get an ordinary quote, list or
document wrong; a wrapper or fork of a listed package is left out too. The list comes from npm
searches on 2026-10-28 for "adf markdown", "markdown to adf", "adf to markdown", "atlassian document
format" and "adf converter".
or from markdown, whatever its downloads: one that starts and converts anything is listed, and its
row says where it fails ordinary input. A wrapper or fork of a listed package is left out. The list
comes from npm searches on 2026-10-28 for "adf markdown", "markdown to adf", "adf to markdown",
"atlassian document format" and "adf converter".
On 2026-10-28, [`converter-comparison/`](https://github.com/larvit/adf-codec/tree/main/converter-comparison)
ran each package's published code, at the version the table names, with its default options. A
@@ -265,6 +264,7 @@ holding the same marks and link.
| `@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 |
| `@faulander/md2adf` 1.0.0 | both ways | a different document: the status is gone, the mention's `id` becomes its text and the panel a quote | dropped with its text | markdown | 2 |
| `@nthings.dev/adf4j-wasm` 1.0.2 | ADF to markdown | – | replaced by the text `[Unsupported: futureThing]` | GitHub Flavored Markdown, from WebAssembly | 0 |
| `@wrtnlabs/markdown-to-adf` 1.0.2 | markdown to a list of blocks, not a document; fails ordinary input: `***bold italic***` comes out as italic text holding asterisks, and a paragraph holding a hard break stands between blocks | – | – | markdown | 2 |
| `adf-converter` 0.1.0 | ADF to markdown; writes a mention as `@@Ann` | – | its text kept, with a console message | markdown | 0 |
| `adf-md` 0.2.0 | both ways | a different document: the status without its `localId`, the marks in the other order | dropped with its text | markdown with MDX tags for panels, mentions and statuses | 6 |
| `adf-to-markdown` 1.0.1 | ADF to markdown | – | dropped with its text | markdown | 0 |
@@ -272,8 +272,10 @@ holding the same marks and link.
| `adf2markdown` 1.2.0 | ADF to markdown | – | its text kept | markdown | 0 |
| `extended-markdown-adf-parser` 2.4.0 | both ways | a different document: the mention comes back as linked text, the status without its `localId` | written as JSON, read back as a paragraph of that JSON's text | markdown | 9 |
| `github-markdown-adf` 1.3.0 | both ways | a different document: the mention comes back as text, the status as inline code, the marks in the other order | dropped with its text | markdown | 3 |
| `markdown-to-adf` 0.2.20 | markdown to ADF; fails ordinary input: a quote is written as the node type `blockQuote`, which ADF spells `blockquote` | – | – | markdown | 3 |
| `marklassian` 1.2.1 | markdown to ADF | – | – | markdown | 1 |
| `md-adf` 0.2.2 | both ways, with a warning for each fallback | a different document: the mention and the status come back as text, the marks in the other order, the panel as a quote | dropped with its text, with a warning | markdown | 5 |
| `md-to-adf` 0.6.4 | markdown to ADF; fails ordinary input: each list item is written as a list of its own | – | – | markdown | 2 |
| `mdast-util-from-adf` 2.3.0 | ADF to an mdast tree, which `mdast-util-to-markdown` 2.2.1 writes as markdown; throws on a status | – | throws | markdown | 3 |
The next table lists converters this comparison does not run: other ecosystems' libraries,
+1 -1
View File
@@ -1,5 +1,5 @@
#!/bin/sh
# Keep these versions and --before in step with the README's comparison table and the packages it leaves out.
# Keep these versions and --before in step with the README's comparison table.
set -eu
here=$(cd "$(dirname "$0")" && pwd)
node_image=node:26.12.1-alpine3.24
+9
View File
@@ -1022,3 +1022,12 @@ A later override replaces an earlier one's rule, so each subdirectory's override
format's ban on the other format, and `ci.sh` probes every override. They are lint rules because the technical principles refuse a
test that scans the source, and a lint rule reads every import spelling: `from`, a bare `import`,
double quotes and a dynamic `import()`.
## The comparison table lists every converter that starts and converts
2026-10-28, the maintainer, answering the bar for the README's "Other ADF converters" table. It
serves goal 3: a developer choosing a converter sees every one, and what it gets wrong.
A converter that starts and converts anything stays in its table, however poorly. Its row says where
it fails ordinary input, such as a list or a quote. A converter that doesn't start, or needs a page
rather than Node, goes in the second table. A wrapper or fork of a listed package is left out.