From 16fa33e19bb0801d89ddd1875bd56df46fc29779 Mon Sep 17 00:00:00 2001 From: Lilleman auf Larv Date: Thu, 5 Nov 2026 18:36:34 +0100 Subject: [PATCH] =?UTF-8?q?Answer=20prose=20round=201:=201=20=F0=9F=94=B4,?= =?UTF-8?q?=203=20=F0=9F=9F=A1=20(0=20misread);=20drop=20the=20false=20ESM?= =?UTF-8?q?=20claim,=20mark=20ADF=20marks,=20name=20the=20REST=20API=20and?= =?UTF-8?q?=20the=20bodied=20macro?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 8 ++++---- converter-comparison/run.sh | 2 +- docs/announcement-posts.md | 30 ++++++++++++++---------------- 3 files changed, 19 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index ebdc4cb..e1f8f8d 100644 --- a/README.md +++ b/README.md @@ -32,7 +32,7 @@ Atlaskit's markdown transformer converts markdown to ADF, and its ADF to markdow npm install @larvit/adf-codec ``` -ESM only, Node 18 or later ([The package](#the-package)). Upgrading from `0.1.0`: +ESM only, Node 18 or later ([The package](#the-package)). Upgrading: [MIGRATION.md](https://github.com/larvit/adf-codec/blob/main/MIGRATION.md). ## Quick start @@ -253,8 +253,8 @@ comes from npm searches on 2026-11-05 for "adf markdown", "markdown to adf", "ad "atlassian document format" and "adf converter". On 2026-11-05, [`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 -package writing markdown got a document holding marks, a link, a mention, a status, a panel and a +ran each other package's published code at the version the table names, and this package's latest +release, with default options. A package writing markdown got a document holding marks, a link, a mention, a status, a panel and a list, and a document holding a node type it cannot know. A package reading markdown got markdown holding the same marks and link. @@ -785,7 +785,7 @@ All three commands need only Docker, git and bash 5. ## Links - [Changelog](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) +- [Upgrading](https://github.com/larvit/adf-codec/blob/main/MIGRATION.md) - [The lossless flavour's grammar, `spec/flavour.md`](https://github.com/larvit/adf-codec/blob/main/spec/flavour.md) - [Decisions](https://github.com/larvit/adf-codec/blob/main/docs/decisions.md) - [Plan](https://github.com/larvit/adf-codec/blob/main/todo.md) diff --git a/converter-comparison/run.sh b/converter-comparison/run.sh index d0b97d2..3225296 100755 --- a/converter-comparison/run.sh +++ b/converter-comparison/run.sh @@ -1,6 +1,6 @@ #!/bin/sh # Keep these versions and --before in step with the README's comparison table. -# --before reads a bare date as midnight UTC, so the day after the run date keeps that day's publishes. +# --before reads a bare date as midnight UTC, so the day after the run date includes that day's publishes. set -eu here=$(cd "$(dirname "$0")" && pwd) node_image=node:26.13.0-alpine3.24 diff --git a/docs/announcement-posts.md b/docs/announcement-posts.md index aafbec4..e2112d3 100644 --- a/docs/announcement-posts.md +++ b/docs/announcement-posts.md @@ -1,9 +1,7 @@ # Announcement posts for 0.3.0 -Drafts for the maintainer to post, one per place. Each post opens with the asker's problem, says how -the package solves it, then links the repository, whose README opens on what the package is, and the -[comparison table](https://github.com/larvit/adf-codec#other-adf-converters). The Turndown sample in -the first post ran against `0.3.0` on 2026-11-05. Each post says its author maintains the package. +Drafts for the maintainer to post, one per place. The Turndown sample under Topic 96176 ran against +`0.3.0` on 2026-11-05. Delete this file once the posts are out. @@ -18,7 +16,7 @@ Plain text, so it pastes into Jira's comment editor whatever its mode. > Atlaskit transformer's `encode` throws "This is not implemented yet"; here `adfToPortableMarkdown` > and `adfToLosslessMarkdown` write the markdown, and `losslessMarkdownToAdf` reads the lossless one > back to the same document, panels, mentions, statuses and unknown node types included. Every call -> returns a result and never throws. I maintain it. +> returns a result and never throws. Wiki markup is not covered. I maintain it. > > https://github.com/larvit/adf-codec > How it compares with the other npm packages, run on their published code: @@ -30,8 +28,7 @@ Plain text, so it pastes into Jira's comment editor whatever its mode. ### Topic 96176, "Is there a way to convert from HTML to ADF using TypeScript on NodeJS?" -> `@atlaskit/editor-markdown-transformer` doesn't load as ESM in plain Node, so the Turndown route -> above stops at the import. I maintain [`@larvit/adf-codec`](https://github.com/larvit/adf-codec), +> The Turndown route above stops where the Atlaskit packages won't import as ESM, as you found. I maintain [`@larvit/adf-codec`](https://github.com/larvit/adf-codec), > which reads markdown into ADF with no Atlaskit, no React and no dependencies, as ESM that runs in > Node, Forge and browsers. It takes the place of the Atlaskit transformer in that route: > @@ -69,11 +66,11 @@ Plain text, so it pastes into Jira's comment editor whatever its mode. ### Topic 86214, "Add a comment in Rovo action" -> The Atlaskit transformers don't bundle in the Forge backend, but a plain function does: +> The Atlaskit transformers can't be used in the Forge backend, but a plain function can: > [`@larvit/adf-codec`](https://github.com/larvit/adf-codec) (I maintain it) turns the markdown an > agent writes into a valid ADF comment body, with no Atlaskit, no React and no dependencies: > `const body = portableMarkdownToAdf(markdown)`, then send `body.value` as the comment's `body` -> when `body.ok`. Headings, lists, tables, code blocks, links and marks all come out as ADF nodes, +> when `body.ok`. Headings, lists, tables, code blocks, links and marks all come out as ADF nodes and marks, > and an invalid input returns an error instead of throwing. > [Comparison with the other npm packages](https://github.com/larvit/adf-codec#other-adf-converters). @@ -82,7 +79,7 @@ Plain text, so it pastes into Jira's comment editor whatever its mode. > To the question of what else converts markdown to ADF and back: [`@larvit/adf-codec`](https://github.com/larvit/adf-codec), > which I maintain. It is a library, so it doesn't publish to Confluence or ship an Obsidian plugin. > It reads markdown into ADF (CommonMark, GFM tables, task lists and alerts, Obsidian callouts) and -> writes ADF back as markdown, and the lossless pair gives back the original document, panels, +> writes ADF back as markdown, and `adfToLosslessMarkdown` with `losslessMarkdownToAdf` gives back the original document, panels, > mentions, statuses, macros and node types it doesn't know included. Models can edit that markdown, > since it is markdown, which suits the MD to ADF need for LLMs mentioned above. > [Comparison with the other npm packages](https://github.com/larvit/adf-codec#other-adf-converters). @@ -91,9 +88,10 @@ Plain text, so it pastes into Jira's comment editor whatever its mode. > I can't change what the server accepts, but a client that reads ADF over REST can avoid the loss > itself. [`@larvit/adf-codec`](https://github.com/larvit/adf-codec) (I maintain it) writes ADF as -> markdown in which media nodes, mentions, panels, statuses, macros and unknown node types are kept -> as small `!adf:` spellings, and reads that markdown back to the same document. The model edits the -> markdown, and `losslessMarkdownToAdf` gives ADF to send, with the media node still in it. +> markdown in which media nodes, mentions, panels, statuses and macros are kept as `!adf:` lines and +> node types it doesn't know as fenced JSON, and reads that markdown back to the same document. The +> model edits the markdown, and `losslessMarkdownToAdf` gives ADF to send with the REST API, with the +> media node still in it. > [Comparison with the other npm packages](https://github.com/larvit/adf-codec#other-adf-converters). ## GitHub, `atlassian/atlassian-mcp-server` @@ -110,11 +108,11 @@ of their own. > and runs in Node, Deno, Bun and browsers. > [Comparison with the other npm packages](https://github.com/larvit/adf-codec#other-adf-converters). -### Issue 161, "Lossless markdown round-trip for Confluence macros and large-page support via file-path parameter" (optional) +### Issue 161, "Lossless markdown round-trip for Confluence macros and large-page support via file-path parameter" > The first proposal, macros surviving a markdown round-trip, is what [`@larvit/adf-codec`](https://github.com/larvit/adf-codec) -> (I maintain it) does for any client: `adfToLosslessMarkdown` writes a macro as an `!adf:extension` -> line holding its key, type and parameters, and `losslessMarkdownToAdf` restores it exactly. +> (I maintain it) does for any client: `adfToLosslessMarkdown` writes a macro as an `!adf:extension` or +> `!adf:bodiedExtension` directive holding its key, type and parameters, and `losslessMarkdownToAdf` restores it exactly. > [Comparison with the other npm packages](https://github.com/larvit/adf-codec#other-adf-converters). ## Left out