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

Answer prose round 1: 0 🔴, 8 🟡; say which reader skips what, reorder the migration's keep-the-mark advice, file the decision title as a question

This commit is contained in:
2026-10-14 20:57:30 +02:00
parent 01f1773677
commit d8fbff6fde
8 changed files with 44 additions and 36 deletions
+10 -11
View File
@@ -2,23 +2,22 @@
## From `0.2.0` to `0.3.0`
A mark spelling skips a node Atlassian's schema withholds the mark from, in `losslessMarkdownToAdf`, and
skips code text in every reader:
Every reader skips code text when it spells a mark other than a link, and `losslessMarkdownToAdf`
also skips every other node Atlassian's schema withholds the mark from:
| Input | `0.2.0` | `0.3.0` |
| --- | --- | --- |
| a `date`, `emoji`, `inlineCard`, `mention`, `status` or `mediaInline` inside a mark's spelling (`**!adf:mention[@A]{id=x}**`) | the node holds the mark | the node holds only marks its type takes; text beside it keeps the mark |
| a link around only nodes that cannot take it, hard breaks aside, or a directive mark around only such nodes or code spans (`[!adf:status[Done]{color=green}](/u)`) | the nodes hold the mark | `unsupported-node-shape`; write the mark around text beside them |
| a code span inside any mark's spelling but a link's (``**`npm ci`**``), in every reader | the code text holds the mark | the code text holds only `code` and the link |
| a code span inside any mark's spelling but a link's (``**`npm ci`**``) | the code text holds the mark | the code text holds only `code`, and a link where one wraps it |
`0.2.0` wrote these spellings for a node holding such a mark; `0.3.0` writes the node as
`!adf:carry{json="…"}`. `0.3.0` reads markdown stored from such a document without the mark, or
refuses it where the mark wrapped such nodes alone. Written back, a space beside such a node inside
the mark's spelling becomes `!adf:text{text=" "}`: ``**Run `npm ci` first**`` writes back as
``**Run!adf:text{text=" "}**`npm ci`**!adf:text{text=" "}first**``. A kept mark is one Atlassian's
schema withholds, so a site may refuse the document: keep one only in markdown written from ADF that
held it. To keep the mark, read the markdown with `0.2.0` and write it with `0.3.0`, installed side
by side:
`0.3.0`'s `adfToLosslessMarkdown` writes a node holding a withheld mark as `!adf:carry{json="…"}`,
where `0.2.0` wrote these spellings. `0.3.0` reads markdown stored from such a document without the
mark, and refuses it where the mark wrapped only those nodes. Written back, a space beside the node
inside the mark's spelling becomes `!adf:text{text=" "}`: ``**Run `npm ci` first**`` writes back as
``**Run!adf:text{text=" "}**`npm ci`**!adf:text{text=" "}first**``. Keep the mark only in markdown
written from ADF that held it: Atlassian's schema withholds it, so a site may refuse the document.
To keep it, read the markdown with `0.2.0` and write it with `0.3.0`, installed side by side:
```sh
npm install @larvit/adf-codec@0.3.0 adf-codec-0.2@npm:@larvit/adf-codec@0.2.0