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

Answer stability round 1: item 71 waits on items 7 and 46 again, keywords match the GitHub topics

This commit is contained in:
2026-10-05 00:24:20 +02:00
committed by Lillem4n
parent 3fb21b9766
commit f4022d62c9
4 changed files with 37 additions and 34 deletions
+9 -24
View File
@@ -10,17 +10,19 @@ products store as ADF.
- **Lossless:** `adfToMarkdown` and `markdownToAdf` give back the document they started from —
panels, mentions, statuses and node types this version does not know included.
- **Plain CommonMark in:** a bot's or a model's markdown is valid input, nothing to learn first.
- **Plain markdown out:** `adfToPlainMarkdown` and `plainMarkdownToAdf` convert to and from what
GitHub, GitLab and Obsidian render — GitHub Flavored Markdown's alerts and task lists, Obsidian
Flavored Markdown's callouts, highlights and pipe tables — keeping the content.
- **Plain CommonMark in:** a bot's or a model's markdown is valid input, apart from raw HTML and
the exceptions [The guarantees](#the-guarantees) lists.
- **Plain markdown, lossy:** `adfToPlainMarkdown` and `plainMarkdownToAdf` convert to and from
markdown GitHub, GitLab and Obsidian render — GitHub Flavored Markdown's alerts, task lists and
pipe tables, Obsidian Flavored Markdown's callouts and highlights. They keep the text, images and
link targets and drop the rest; to save edits back, use the lossless pair.
- **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.
- **HTML** at `0.2.0`: `adfToHtml`, `htmlToAdf`, `markdownToHtml`, `htmlToMarkdown`.
- **HTML at `0.2.0`:** `adfToHtml`, `htmlToAdf`, `markdownToHtml`, `htmlToMarkdown`.
[Goals](#goals) · [Audience](#audience) · [The shape](#the-shape) ·
[Other ADF converters](#other-adf-converters) · [Plain markdown](#plain-markdown) ·
[The errors](#the-errors) · [The guarantees](#the-guarantees) · [The package](#the-package) ·
[Plain markdown](#plain-markdown) · [The errors](#the-errors) · [The guarantees](#the-guarantees) ·
[The package](#the-package) ·
[Grammar](https://github.com/larvit/adf-codec/blob/main/spec/flavour.md) ·
[Changes](https://github.com/larvit/adf-codec/blob/main/CHANGELOG.md) ·
[Upgrading from `0.1.0`](https://github.com/larvit/adf-codec/blob/main/MIGRATION.md) ·
@@ -99,23 +101,6 @@ htmlToMarkdown(html: string): Result<string> // 0.2.0
`Result<T>` is `{ ok: true; value: T } | { ok: false; error: ConvertError }` — nothing throws.
## Other ADF converters
Serves Goal 3. Each package's latest version on npm, checked 2026-10-05 against its docs and by
converting a document holding a paragraph, a mention, a status, an info panel and an unknown node
type to markdown and back.
| Package | ADF to markdown | Markdown to ADF | Round-trip | Invalid ADF | Runtime dependencies |
| --- | --- | --- | --- | --- | --- |
| `@larvit/adf-codec` | yes | yes | deep-equal | returns `not-an-adf-document` | 0 |
| `@atlaskit/editor-markdown-transformer` 6.3.1 | no: `encode` throws | yes, through `@atlaskit/editor-json-transformer` | — | — | 5 |
| `marklassian` 1.2.1 | no | yes | — | — | 1 |
| `adf-to-md` 1.2.1 | yes | no | — | throws | 1 |
| `extended-markdown-adf-parser` 2.4.0 | yes | yes | lossy: the mention reads back as a link, the status loses its `localId`, the unknown node as its JSON in a paragraph | writes empty markdown | 9 |
| `md-to-adf` 0.6.4 | no | yes | — | — | 2 |
| `adf-to-markdown` 1.0.1 | yes | no | — | throws on `null`, writes empty markdown for a `doc` without `content` | 0 |
| `adf2markdown` 1.2.0 | yes | no | — | throws on `null`, writes a newline for a `doc` without `content` | 0 |
## Plain markdown
Serves Goal 7. Plain markdown is a second flavour of the same grammar. `adfToPlainMarkdown` writes