diff --git a/AGENTS.md b/AGENTS.md index cba1509..775eb5d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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 diff --git a/CHANGELOG.md b/CHANGELOG.md index 6207f2f..d7dcfd5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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. diff --git a/MIGRATION.md b/MIGRATION.md index 201a1bd..dead0a4 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -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` diff --git a/README.md b/README.md index 5c340e8..b90c571 100644 --- a/README.md +++ b/README.md @@ -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. diff --git a/docs/decisions.md b/docs/decisions.md index b6a9e7f..ea52cc5 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -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. diff --git a/spec/flavour.md b/spec/flavour.md index 1e20bca..4af0065 100644 --- a/spec/flavour.md +++ b/spec/flavour.md @@ -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