3
0
mirror of https://github.com/larvit/adf-codec.git synced 2026-11-12 11:48:29 +01:00

Record the marks and colwidth spellings in the spec, decisions, changelog and migration guide

This commit is contained in:
2026-10-14 10:00:07 +02:00
committed by Lillem4n
parent e882b5de7a
commit d5b9356a29
5 changed files with 21 additions and 13 deletions
+1
View File
@@ -16,6 +16,7 @@ In `docs/decisions.md`:
- A list right after one of its kind takes the other marker
- An empty key spells `empty`
- `-0` is spelled `-0`
- A block's marks are named, and `colwidth` is a comma list
- Empty markdown is a document of no blocks
- Unknown nodes ride the carry
- The carry fence names the node type
+4
View File
@@ -66,6 +66,10 @@
- **Breaking:** `adfToLosslessMarkdown` writes a centered, uncaptioned external image whose one
mark is a link holding only `href` and `title` as `[![alt](url)](href "title")`, where it wrote the
`mediaSingle` directive. Convert stored markdown per `MIGRATION.md`.
- **Breaking:** `colwidth` is spelled as its widths joined by commas, `colwidth="340,420"`, where it
was a JSON array, and a block's `marks` names each mark with its attributes,
`marks="breakout{mode=wide}"`, where it was a JSON array. The JSON array stays only for a block
mark the flavour does not list. Convert stored markdown per `MIGRATION.md`.
- Fix the time `adfToLosslessMarkdown` and `adfToPortableMarkdown` take on text holding a long run of
`*`, `_`, `~` or backticks, or a heading ending in a long run of `#`: the time is linear in the
run, and a run of 20000 `*` takes milliseconds where it took seconds.
+2
View File
@@ -67,6 +67,8 @@ function migrateMarkdown(stored: string) {
| `\:` keeps a directive literal | `\!adf:` keeps a directive literal |
| `:adf{json="…"}` carrying a link for its `collection`, `id` or `occurrenceKey` | `!adf:link[text]{attrs}` |
| `::listBreak` between two lists of a kind | no separator: adjacent lists of a kind alternate `- ` and `* `, or `1.` and `1)` |
| `colwidth="[340,420]"` | `colwidth="340,420"` |
| `marks="[{\"attrs\":{\"mode\":\"wide\"},\"type\":\"breakout\"}]"` on a block | `marks="breakout{mode=wide}"`; the JSON array stays for a mark the flavour does not list |
A colon run and `:name[` are plain text now, and `adf` an ordinary code block language; text
holding an unescaped `!adf:` and a code fence whose info string opens `adf:` are claimed instead.
+14
View File
@@ -100,6 +100,20 @@ holding no `content` key. A writer panel chose the spelling, 5 of 7. The grammar
`-0` is spelled `-0` wherever the flavour writes a number or a JSON value, since JSON's grammar
reads it back as `-0`. The grammar: `spec/flavour.md` §Block nodes and §The CommonMark blocks.
## A block's marks are named, and `colwidth` is a comma list
2026-10-03 for `colwidth`, 5 of 7, and 2026-10-14 for `marks`, 3 of 3: writer panels of product
managers, engineers and support agents. Goal 6. Valid while ADF types these attributes as
`src/adf/` does.
`colwidth` is its widths joined by commas, `colwidth="340,420"`, where it was a JSON array. A
block's `marks` names each mark with its `{attrs}`, in order,
`marks="indentation{level=2} fragment{localId=f1 name=\"Price list\"}"`, chosen over the escaped
JSON array and an unquoted one. All three writers first sketched a key per mark, `{align=center}`,
which loses the marks' order and can clash with the node's own attributes. A mark `src/adf/` does not
type keeps the whole array as JSON, the general form (§Readable spellings take the `try` prefix).
The grammar: `spec/flavour.md` §Block nodes.
## Empty markdown is a document of no blocks
2026-10-03, a writer panel and the maintainer. Goals 1 and 6. Valid while ADF's schema requires
-13
View File
@@ -25,8 +25,6 @@
| ID | Release | Exempt | Item | R | S | C | A | G | Goals | Score |
|---|---|---|---|---|---|---|---|---|---|---|
| 52 | 0.2.0 | | **Spell `colwidth` as a comma list, `colwidth="340,420"`.** | 3 | 3 | 3 | 5 | 6 | 6 | 11.5 |
| 53 | 0.2.0 | | **Put a block's `marks` spelling to the writer panel and adopt its pick.** | 4 | 5 | 4 | 5 | 6 | 6 | 10.0 |
| 111 | 0.2.1 | | **Split README's `unsupported-node-shape` error-table row into one bullet per cause group, each carrying its remedy.** | 2 | 2 | 1 | 5 | 5 | 3 | 15.3 |
| 89 | 0.2.1 | | **Build a `date`, `emoji`, `inlineCard`, `mention` or `status` holding no mark Atlassian's schema withholds from it, in every reader.** | 4 | 4 | 4 | 5 | 6 | 4 | 13.0 |
| 99 | 0.2.1 | defect | **Write a linked external image standing inline or in a table cell in the spelling a reader panel picks, in `adfToPortableMarkdown`.** | 3 | 3 | 5 | 6 | 7 | 7 | 12.9 |
@@ -73,17 +71,6 @@
## Details
### 52. Spell `colwidth` as a comma list, `colwidth="340,420"`.
A writer panel chose it on 2026-10-03, 5 of 7, over today's `colwidth="[340,420]"`. Breaking:
`MIGRATION.md`'s Spellings table gains its row.
### 53. Put a block's `marks` spelling to the writer panel and adopt its pick.
Today `marks="[{\"attrs\":{\"mode\":\"wide\"},\"type\":\"breakout\"}]"`, the marks array as
escaped JSON. Breaking where the panel picks another spelling: `MIGRATION.md`'s Spellings table
gains its row.
### 111. Split README's `unsupported-node-shape` error-table row into one bullet per cause group, each carrying its remedy.
The row's "Fires when" cell holds about a dozen causes in four groups (parsing, each writer, both