From 55968bbd26ffea41f52520510f9bfb112cad9f17 Mon Sep 17 00:00:00 2001 From: Lilleman auf Larv Date: Wed, 28 Oct 2026 23:43:15 +0100 Subject: [PATCH] List the three converters that fail ordinary input, each with where it fails --- AGENTS.md | 1 + CHANGELOG.md | 2 +- README.md | 12 +++++++----- converter-comparison/run.sh | 2 +- docs/decisions.md | 9 +++++++++ 5 files changed, 19 insertions(+), 7 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 05fa255..b6d5a82 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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 diff --git a/CHANGELOG.md b/CHANGELOG.md index 1a62300..89ed0be 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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`, diff --git a/README.md b/README.md index fb5db26..94a1abf 100644 --- a/README.md +++ b/README.md @@ -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, diff --git a/converter-comparison/run.sh b/converter-comparison/run.sh index 04283c2..54d07cc 100755 --- a/converter-comparison/run.sh +++ b/converter-comparison/run.sh @@ -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 diff --git a/docs/decisions.md b/docs/decisions.md index db85695..c6e7932 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -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.