mirror of
https://github.com/larvit/adf-codec.git
synced 2026-11-19 22:55:44 +01:00
Document the !adf:{…} marker and the 0.3 directives it replaces
This commit is contained in:
@@ -24,6 +24,7 @@ In `docs/decisions.md`:
|
||||
- Foreign HTML reads best effort and is never refused
|
||||
- Names stay text
|
||||
- Directives under `!adf:`
|
||||
- A CommonMark block's `localId` rides an `!adf:{…}` marker beside its spelling
|
||||
- CommonMark is a subset
|
||||
- Tables
|
||||
- Links
|
||||
|
||||
@@ -2,6 +2,7 @@
|
||||
|
||||
## 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 `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.
|
||||
|
||||
@@ -33,6 +33,19 @@ for (const element of document.querySelectorAll('[data-text-color]')) element.st
|
||||
|
||||
`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:
|
||||
|
||||
- A body row holding fewer cells than the header is padded with empty cells, where `0.3.1`
|
||||
|
||||
@@ -471,7 +471,8 @@ Ping !adf:mention[@Mikael]{id=5b10a2} — !adf:status[In review]{color=yellow}
|
||||
|
||||
| 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 |
|
||||
| `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 |
|
||||
@@ -661,7 +662,7 @@ Which reader raises which code: [The calls](#the-calls). Codes every direction r
|
||||
|
||||
| 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 `\\|` |
|
||||
| `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 |
|
||||
@@ -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;
|
||||
- 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;
|
||||
- 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
|
||||
document;
|
||||
- carries a node the writers' cause below names, such as an inline card a link marks.
|
||||
|
||||
@@ -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
|
||||
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
|
||||
|
||||
2026-08-23, the maintainer. Goal 5. Valid while prose rarely writes the shapes the carve-outs claim.
|
||||
|
||||
+38
-7
@@ -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).
|
||||
|
||||
**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
|
||||
line, `[` or `{` an inline directive. A `!adf:` completing none of the three is a named error, and
|
||||
`\!adf:` is the literal, block and inline alike. A construct CommonMark binds first — a code span,
|
||||
closes a container, `{` opens a marker, and a name picks by what follows it in turn — a space or
|
||||
the line's end a block line, `[` or `{` an inline directive. A `!adf:` completing none of the four
|
||||
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
|
||||
`[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
|
||||
@@ -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.
|
||||
|
||||
**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
|
||||
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
|
||||
@@ -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
|
||||
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
|
||||
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
|
||||
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
|
||||
|
||||
CommonMark spells `blockquote`, `bulletList`, `codeBlock`, `heading`, `listItem`, `orderedList`,
|
||||
`paragraph` and `rule`, and keeps that spelling wherever it holds what the node carries. What it
|
||||
cannot — `localId` (string) on any of them, marks, and the values below — takes the directive
|
||||
form.
|
||||
`paragraph` and `rule`, and keeps that spelling wherever it holds what the node carries, a
|
||||
`localId` riding a marker (Directives). What neither holds — marks, any other attribute, and the
|
||||
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).
|
||||
- `codeBlock` — container, body one fenced code block per text node, each fence's info string the
|
||||
|
||||
Reference in New Issue
Block a user