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

Document the !adf:{…} marker and the 0.3 directives it replaces

This commit is contained in:
2026-11-19 16:47:40 +01:00
committed by Lillem4n
parent acdc6e2c76
commit e728d6d251
6 changed files with 77 additions and 10 deletions
+1
View File
@@ -24,6 +24,7 @@ In `docs/decisions.md`:
- Foreign HTML reads best effort and is never refused - Foreign HTML reads best effort and is never refused
- Names stay text - Names stay text
- Directives under `!adf:` - Directives under `!adf:`
- A CommonMark block's `localId` rides an `!adf:{…}` marker beside its spelling
- CommonMark is a subset - CommonMark is a subset
- Tables - Tables
- Links - Links
+1
View File
@@ -2,6 +2,7 @@
## Unreleased ## Unreleased
- **Breaking:** `adfToLosslessMarkdown` writes a paragraph, heading, quote, list, list item, code block or rule holding a `localId` in its CommonMark spelling, the id in an `!adf:{localId=…}` marker beside it, where `0.3.1` wrote the block as a directive, so a Jira document reads as markdown. `losslessMarkdownToAdf` still reads the directives `0.3.1` wrote.
- Add `jiraWikiToAdf`, which reads Jira wiki markup into ADF, `{adf}` macros included, and refuses only a broken `{adf}` macro and markup past the nesting or engine limits. - Add `jiraWikiToAdf`, which reads Jira wiki markup into ADF, `{adf}` macros included, and refuses only a broken `{adf}` macro and markup past the nesting or engine limits.
- Add `adfToLosslessJiraWiki`, which writes ADF as Jira wiki markup and carries each node or mark wiki markup cannot spell in Jira's `{adf}` macro, so nothing is lost. - Add `adfToLosslessJiraWiki`, which writes ADF as Jira wiki markup and carries each node or mark wiki markup cannot spell in Jira's `{adf}` macro, so nothing is lost.
- **Breaking:** `commonMarkToAdf`, `losslessMarkdownToAdf` and `portableMarkdownToAdf` match a link reference to its definition under Unicode case folding, where `0.3.1` lowercased the label. `[ẞ]` with `[SS]: /url` reads as a link, and where two definitions' labels fold together, the first wins. `ı` and `I` stay two labels. - **Breaking:** `commonMarkToAdf`, `losslessMarkdownToAdf` and `portableMarkdownToAdf` match a link reference to its definition under Unicode case folding, where `0.3.1` lowercased the label. `[ẞ]` with `[SS]: /url` reads as a link, and where two definitions' labels fold together, the first wins. `ı` and `I` stay two labels.
+13
View File
@@ -33,6 +33,19 @@ for (const element of document.querySelectorAll('[data-text-color]')) element.st
`htmlToAdf` still reads the HTML `0.3.1` wrote. `htmlToAdf` still reads the HTML `0.3.1` wrote.
`adfToLosslessMarkdown` writes a paragraph, heading, quote, list, list item, code block or rule
whose one attribute CommonMark can't spell is `localId` in its CommonMark spelling, the id in an
`!adf:{localId=…}` marker, where `0.3.1` wrote its directive:
| `0.3.1` | `0.4.0` |
| --- | --- |
| `!adf:heading {level=2 localId=h1}`, `Background`, `!adf:/heading` | `## Background !adf:{localId=h1}` |
| `!adf:paragraph {localId=p1}`, `Text`, `!adf:/paragraph` | `!adf:{localId=p1}` above `Text` |
| `!adf:bulletList {localId=l1}`, `!adf:listItem {localId=i1}`, … | `!adf:{localId=l1}` above `- !adf:{localId=i1} Item !adf:{localId=p1}` |
`losslessMarkdownToAdf` still reads the directives `0.3.1` wrote. Code that searches stored lossless
markdown for these directives, or a test pinning its text, needs the new spelling.
`portableMarkdownToAdf` reads more of GFM's pipe table: `portableMarkdownToAdf` reads more of GFM's pipe table:
- A body row holding fewer cells than the header is padded with empty cells, where `0.3.1` - A body row holding fewer cells than the header is padded with empty cells, where `0.3.1`
+6 -3
View File
@@ -471,7 +471,8 @@ Ping !adf:mention[@Mikael]{id=5b10a2} — !adf:status[In review]{color=yellow}
| ADF | Directive | | ADF | Directive |
| --- | --- | | --- | --- |
| `blockquote`, `bulletList`, `codeBlock`, `heading`, `listItem`, `orderedList`, `paragraph`, `rule` carrying `localId`, marks or a value CommonMark cannot spell | the same node in directive form, `!adf:paragraph {localId=…}` | | `blockquote`, `bulletList`, `codeBlock`, `heading`, `listItem`, `orderedList`, `paragraph`, `rule` carrying `localId` | the CommonMark spelling with a marker: `!adf:{localId=…}` on the line above, after a list item's marker, or at the end of a heading's line and of the last line of a quote's or list item's first paragraph |
| the same nodes carrying marks or a value neither CommonMark nor a marker spells | the same node in directive form, `!adf:paragraph {marks=…}` |
| `border` | an inline directive mark around a `mediaInline`, the one inline node that takes it | | `border` | an inline directive mark around a `mediaInline`, the one inline node that takes it |
| `caption`, `media`, `mediaGroup`, `mediaSingle` | the media family; an image CommonMark cannot spell, a stored file, a caption | | `caption`, `media`, `mediaGroup`, `mediaSingle` | the media family; an image CommonMark cannot spell, a stored file, a caption |
| `date`, `emoji`, `inlineCard`, `mediaInline`, `mention`, `status` | inline leaves; `emoji`, `mention` and `status` spell their `text` in the `[content]` slot | | `date`, `emoji`, `inlineCard`, `mediaInline`, `mention`, `status` | inline leaves; `emoji`, `mention` and `status` spell their `text` in the `[content]` slot |
@@ -661,7 +662,7 @@ Which reader raises which code: [The calls](#the-calls). Codes every direction r
| Code | Fires when | What you can do | | Code | Fires when | What you can do |
| --- | --- | --- | | --- | --- | --- |
| `malformed-directive` | an `!adf:` the grammar cannot read — a prefix completing no directive, an unclosed container, `[content]` or `{attrs}`, a closer with no container of its name open, a leaf given a body, `{attrs}` out of order or duplicated, invalid JSON in an opaque carry | write the spelling the message names, or keep it literal: escape the prefix — `\!adf:`, block and inline alike — or, for a code fence whose info string opens `adf:`, drop the info string and wrap the fence in `!adf:codeBlock {language="adf:…"}` | | `malformed-directive` | an `!adf:` the grammar cannot read — a prefix completing no directive, an unclosed container, `[content]` or `{attrs}`, a closer with no container of its name open, a leaf given a body, `{attrs}` out of order or duplicated, an `!adf:{…}` marker with no block right below it or two on one block, invalid JSON in an opaque carry | write the spelling the message names, or keep it literal: escape the prefix — `\!adf:`, block and inline alike — or, for a code fence whose info string opens `adf:`, drop the info string and wrap the fence in `!adf:codeBlock {language="adf:…"}` |
| `malformed-pipe-table` | a pipe row that is no pipe table — a missing `---` delimiter row, a delimiter row whose cell count differs from the header's, a body row holding more cells than the header, or short rows whose padding would add more cells than the table holds; in `losslessMarkdownToAdf` also a body row holding fewer cells, an alignment colon, and a header or delimiter row not opening with a pipe | add a `---` row of the header's cell count under the header and give no body row more cells; for `losslessMarkdownToAdf`, also give every row the header's count, open every row with a pipe and drop the colons. To keep the lines literal text, escape the leading pipe of every one — escaping a single row leaves the next to open a fresh table and fail the same way — or, for a table without leading pipes, write one `\|` of its delimiter row as `\\|` | | `malformed-pipe-table` | a pipe row that is no pipe table — a missing `---` delimiter row, a delimiter row whose cell count differs from the header's, a body row holding more cells than the header, or short rows whose padding would add more cells than the table holds; in `losslessMarkdownToAdf` also a body row holding fewer cells, an alignment colon, and a header or delimiter row not opening with a pipe | add a `---` row of the header's cell count under the header and give no body row more cells; for `losslessMarkdownToAdf`, also give every row the header's count, open every row with a pipe and drop the colons. To keep the lines literal text, escape the leading pipe of every one — escaping a single row leaves the next to open a fresh table and fail the same way — or, for a table without leading pipes, write one `\|` of its delimiter row as `\\|` |
| `not-a-string` | the value handed in is not a string, such as `null`, a number or a `String` object | pass the input as a string, `String(value)` for a `String` object; the message names the value's type | | `not-a-string` | the value handed in is not a string, such as `null`, a number or a `String` object | pass the input as a string, `String(value)` for a `String` object; the message names the value's type |
| `unknown-directive-name` | a directive whose name is no node or mark this version spells | check the name in [`spec/flavour.md`](https://github.com/larvit/adf-codec/blob/main/spec/flavour.md), or escape the prefix as `\!adf:`; the spelling itself is well formed, so a later minor may give the name meaning | | `unknown-directive-name` | a directive whose name is no node or mark this version spells | check the name in [`spec/flavour.md`](https://github.com/larvit/adf-codec/blob/main/spec/flavour.md), or escape the prefix as `\!adf:`; the spelling itself is well formed, so a later minor may give the name meaning |
@@ -699,7 +700,9 @@ Every call can raise `engine-limit`, and every conversion `unsupported-nesting-d
hard break, a mention, a code span or, for `border`, text; hard break, a mention, a code span or, for `border`, text;
- writes a link whose text holds something besides hard breaks, but no node that takes a link, - writes a link whose text holds something besides hard breaks, but no node that takes a link,
such as `[!adf:status[Done]{color=green}](/u)`: write the link around text beside them; such as `[!adf:status[Done]{color=green}](/u)`: write the link around text beside them;
- writes as a directive a node or mark the lossless flavour spells as CommonMark; - writes as a directive a node or mark the lossless flavour spells as CommonMark, other than the
directive `0.3` wrote for a block holding a `localId`;
- puts an `!adf:{…}` marker where its block carries none, or gives it a key but `localId`;
- puts `!adf:textBreak{}` where it parts nothing, or `!adf:doc` anywhere but as the whole - puts `!adf:textBreak{}` where it parts nothing, or `!adf:doc` anywhere but as the whole
document; document;
- carries a node the writers' cause below names, such as an inline card a link marks. - carries a node the writers' cause below names, such as an inline card a link marks.
+18
View File
@@ -198,6 +198,24 @@ one escape. Not CommonMark's generic-directives proposal: its `:::` claims a for
its fence-length discipline ties a container's opener to its own body, where closing from the its fence-length discipline ties a container's opener to its own body, where closing from the
opener nests by itself and leaf versus container falls out of the node's content model. opener nests by itself and leaf versus container falls out of the node's content model.
## A CommonMark block's `localId` rides an `!adf:{…}` marker beside its spelling
2026-11-19, the maintainer and a writer panel. Goals 1, 5 and 6. Valid while Jira gives every
block a `localId`.
Jira gives every heading, paragraph, list and list item a `localId`. Written as directives, a Jira
description read as mostly `!adf:` lines, and a `- x` typed into a directive list nested rather
than added an item. The id rides the nameless attribute block `!adf:{localId=…}` instead, beside
the block's CommonMark spelling; the maintainer chose the nameless form. A writer panel of seven
readers seated from README §Audience settled three placements: the line above a blockquote, 5 of 7,
the line above a code block, 5 of 7, and a rule's line above a blank line, 7 of 7. It split 4 to 3
on the paragraph, the heading and the list, and the maintainer picked: the line above a paragraph,
the end of the last line for one opening a quote or list item, the end of a heading's line, the line
above a list, and each item's id after its marker. Only `localId` rides a marker. A block holding
anything else, or an id with no unambiguous place, keeps its directive, a list whole. The
directives 0.3 wrote for these blocks still read. The grammar: `spec/flavour.md` §The CommonMark
blocks.
## CommonMark is a subset ## CommonMark is a subset
2026-08-23, the maintainer. Goal 5. Valid while prose rarely writes the shapes the carve-outs claim. 2026-08-23, the maintainer. Goal 5. Valid while prose rarely writes the shapes the carve-outs claim.
+38 -7
View File
@@ -89,9 +89,9 @@ the leaf that parts two text nodes (Inline nodes). Every fence info string openi
reserved for the block carry (The opaque carry). reserved for the block carry (The opaque carry).
**Claiming**: an unescaped `!adf:` claims wherever it stands. What follows picks the form: `/name` **Claiming**: an unescaped `!adf:` claims wherever it stands. What follows picks the form: `/name`
closes a container, and a name picks by what follows it in turn — a space or the line's end a block closes a container, `{` opens a marker, and a name picks by what follows it in turn — a space or
line, `[` or `{` an inline directive. A `!adf:` completing none of the three is a named error, and the line's end a block line, `[` or `{` an inline directive. A `!adf:` completing none of the four
`\!adf:` is the literal, block and inline alike. A construct CommonMark binds first — a code span, is a named error, and `\!adf:` is the literal, block and inline alike. A construct CommonMark binds first — a code span,
an autolink URI, a link destination or title — holds its `!adf:` as content; a directive's an autolink URI, a link destination or title — holds its `!adf:` as content; a directive's
`[content]`, which binds ahead of bracket matching, does not. A claimed block line also ends a lazy `[content]`, which binds ahead of bracket matching, does not. A claimed block line also ends a lazy
continuation: the blockquote or list item whose paragraph CommonMark would fold it into closes continuation: the blockquote or list item whose paragraph CommonMark would fold it into closes
@@ -123,6 +123,10 @@ code fence or opaque carry is content.
**Block leaf**: `!adf:name arg {attrs}` — the same opener with no closer, `arg` reading as above. **Block leaf**: `!adf:name arg {attrs}` — the same opener with no closer, `arg` reading as above.
**Marker**: `!adf:{localId=…}`, nameless, carries the `localId` of a block CommonMark spells, beside
that spelling: alone on the line above the block, right after a list item's marker, or one space
after the text ending a paragraph's or heading's last line (The CommonMark blocks).
Which of the two a node takes is its content model, never the spelling: a model taking content is Which of the two a node takes is its content model, never the spelling: a model taking content is
written as an opener–closer pair and one taking none as a leaf, so a leaf given a body and a written as an opener–closer pair and one taking none as a leaf, so a leaf given a body and a
container missing its closer are each a named error. A node holding no content whose model takes container missing its closer are each a named error. A node holding no content whose model takes
@@ -201,7 +205,8 @@ The directive name is always the ADF node type. A container's body is the node's
has none. Every directive parses in any position — `losslessMarkdownToAdf` builds exactly what is has none. Every directive parses in any position — `losslessMarkdownToAdf` builds exactly what is
written; validity against ADF's content models stays the author's business (`docs/decisions.md` §No written; validity against ADF's content models stays the author's business (`docs/decisions.md` §No
schema validation). It parses only in the form the emitter picks, though: a directive spelling a schema validation). It parses only in the form the emitter picks, though: a directive spelling a
node the emitter would have written as CommonMark is a named error. node the emitter would have written as CommonMark is a named error. The form 0.3 wrote still reads:
the directive of a CommonMark block holding a `localId`, or of a list an item of which holds one.
Each section lists attributes as `name (type)`. A parenthesized value set documents what real Each section lists attributes as `name (type)`. A parenthesized value set documents what real
payloads hold; the type stays string and any value round-trips verbatim. Values map to attrs by payloads hold; the type stays string and any value round-trips verbatim. Values map to attrs by
@@ -231,9 +236,35 @@ markdown input the same mismatch is a named error.
### The CommonMark blocks ### The CommonMark blocks
CommonMark spells `blockquote`, `bulletList`, `codeBlock`, `heading`, `listItem`, `orderedList`, CommonMark spells `blockquote`, `bulletList`, `codeBlock`, `heading`, `listItem`, `orderedList`,
`paragraph` and `rule`, and keeps that spelling wherever it holds what the node carries. What it `paragraph` and `rule`, and keeps that spelling wherever it holds what the node carries, a
cannot — `localId` (string) on any of them, marks, and the values below — takes the directive `localId` riding a marker (Directives). What neither holds — marks, any other attribute, and the
form. values below — takes the directive form.
Each marker holds `localId` alone, its value spelled as any attribute's is. A paragraph's stands
alone on the line right above it, inside its container's prefix or indentation; the paragraph
opening a quote or a list item spelled in CommonMark ends its last line with its marker instead, one
space after its text, since the line above is the container's. A heading's ends its line, one space
after its text: `## Background !adf:{localId=h1}`. A blockquote's, a code block's and a list's
stands alone on the line right above it. A rule's stands above a blank line, as does a list's whose
marker cannot interrupt a paragraph (Canonical form): CommonMark reads a line of text above either
as part of it. A list item's stands right after its list marker, one space before its first
paragraph's text.
````
!adf:{localId=l1}
- !adf:{localId=i1} First item !adf:{localId=p1}
- !adf:{localId=i2} Second item
!adf:{localId=l2}
- Nested item
> Quoted text !adf:{localId=p3}
````
An empty paragraph or heading holding a `localId` takes the directive form, and so does a list, whole,
one of whose items holds a `localId` beside no first paragraph or opens with a block whose marker
would take the item's first line. A marker anywhere else, holding another key or a value outside
its canonical spelling, standing above no block of its container, or a blank line apart from it
where none is written, is a named error, and so is a block carrying two.
- `blockquote`, `bulletList`, `listItem` — containers, block body. Attributes: `localId` (string). - `blockquote`, `bulletList`, `listItem` — containers, block body. Attributes: `localId` (string).
- `codeBlock` — container, body one fenced code block per text node, each fence's info string the - `codeBlock` — container, body one fenced code block per text node, each fence's info string the