diff --git a/AGENTS.md b/AGENTS.md index eaad46f..50a8db6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -95,6 +95,8 @@ In `docs/decisions.md`: - The feature table is a section per corpus example, led by a summary table - Plain text is blocks a blank line apart, with `• ` and `1.` markers and nesting indented - Jira wiki markup carries what it cannot spell in Jira's `{adf}` macro, and a lossy writer keeps only its content +- Jira wiki markup's writers are `adfToLosslessJiraWiki` and `adfToLossyJiraWiki`, two calls with no option +- Jira wiki markup spellings the help leaves open are a writer panel's picks - `htmlToAdf` reads any HTML, with no option and no second call ## 1. Nothing about any consumer in the library diff --git a/docs/decisions.md b/docs/decisions.md index 2edd175..3c48bb6 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -1457,6 +1457,38 @@ block node, `{adf:display=inline}` for an inline node or a marked run. The round Jira still renders the document. The lossy wiki writer ships beside it for consumers who want wiki markup alone: it drops the form of what wiki markup cannot spell and keeps its content. +Confirmed 2026-11-16 on a live Jira Cloud site: a description holding `{adf:display=block}` around +a `table` node's JSON rendered a table, and `{adf:display=inline}` around a `status` node's JSON +rendered the status lozenge between its neighbouring words. + +## Jira wiki markup's writers are `adfToLosslessJiraWiki` and `adfToLossyJiraWiki`, two calls with no option + +2026-11-16, a developer panel. Goals 6, 7 and 8. Valid while a lossy writer drops form with no +refusal. Lands with `todo.md` items 193 to 196. + +Seven fresh-context readers, seated as the bot, the viewer/editor app and the LLM pipeline, were +told the trap: an app saving through the lossy writer loses form on every save, with nothing +refused. All seven picked `adfToLosslessJiraWiki` and `adfToLossyJiraWiki` as two calls over one +call with `{ lossy: true }`, and over `adfToPortableWiki`, which reads as the safe choice. The +reader's name is not settled in this entry: the seats split four to three between +`jiraWikiMarkupToAdf` and `jiraWikiToAdf`, short of five of seven. + +## Jira wiki markup spellings the help leaves open are a writer panel's picks + +2026-11-16, a writer panel. Goal 11. Valid while a live Jira site renders each pick; the ones its +help does not show, `{note}`, a link's title, an image's `alt`, `\\` inside a cell and +`[~accountid:…]`, wait for the maintainer's check there. Lands with `spec/wiki.md`. + +Atlassian's text formatting notation help is the source for every spelling it shows. For the nine +it leaves open, seven fresh-context readers, seated as wiki-markup authors, each wrote their own +spelling before picking among shuffled candidates, with no rationale and nothing saying what is +implemented. Seven agreed on a one-paragraph blockquote as `bq. `, any other as `{quote}`, a note +panel as `{note}`, underline as `+x+`, a mention as `[~accountid:5b10ac8d82e05b22cc7d4ef5]` and a +cell's two paragraphs as `\\`. Six picked `{noformat}` over `{code:none}` for a code block with no +language, five `[text|url|title]` over dropping the title, five `alt=text` over `alt="text"`. The +first three seats read the brief's first 60 lines, which held a few of its first question's +candidates; the last four read 55. + ## `htmlToAdf` reads any HTML, with no option and no second call 2026-11-15, a developer panel. Goals 6, 8 and 12. Valid while the dialect and foreign HTML read diff --git a/spec/wiki.md b/spec/wiki.md new file mode 100644 index 0000000..fce319e --- /dev/null +++ b/spec/wiki.md @@ -0,0 +1,82 @@ +# Jira wiki markup + +The wiki markup the lossless writer writes, the lossy writer writes and the reader reads, per node +and mark. Its source is Atlassian's "Text Formatting Notation Help", which every Jira site serves at +`/secure/WikiRendererHelpAction.jspa?section=all`; a spelling the help does not show is settled in +`docs/decisions.md` §Jira wiki markup spellings the help leaves open are a writer panel's picks. The +carry is in `docs/decisions.md` §Jira wiki markup carries what it cannot spell in Jira's `{adf}` +macro, and a lossy writer keeps only its content. The written form is contract +(`docs/decisions.md` §The formats are API). + +## The carry + +The lossless writer spells a node or mark wiki markup has no spelling for as Jira's own `{adf}` +macro around ADF JSON: + +- A block node: `{adf:display=block}`, a line feed, the node's JSON, a line feed, `{adf}`. +- An inline node, or a run of inline nodes under a mark wiki markup cannot spell: + `{adf:display=inline}`, the JSON of the node, or the array of the run's nodes, `{adf}`. + +The JSON is compact, and a `{` inside a string is `\u007b`, so the closing `{adf}` stands nowhere +else. A node rides the carry where its type, an attribute or a mark has no spelling in the tables +below, or where its content holds a node that does. The carry holds the nearest block or inline node +that wiki markup can hold in its parent: a `listItem` and a `tableRow` cannot stand alone, so their +list or table rides it. + +The lossy writer writes no `{adf}`. Where the lossless writer carries a node, the lossy writer keeps +what a reader of the rendered document sees, as `adfToPortableMarkdown` does (README §Portable +markdown): the node's text, link targets and titles, its blocks where it holds some, and nothing for +a `placeholder`. A mark the marks table does not spell drops, keeping its text. The lossy writer +also writes a table cell's blocks parted by `\\`. + +## Blocks + +Blocks are parted by one blank line. A document whose `content` is an empty array is the empty +string. + +| ADF | Wiki markup | Reader | +| --- | --- | --- | +| `paragraph` | its inline content | the same; a line feed inside it is a `hardBreak`, as Jira renders it | +| `heading`, `level` 1 to 6 | `h1. ` to `h6. ` | the same | +| `blockquote` of one paragraph | `bq. `, the paragraph | the same | +| `blockquote`, any other | `{quote}`, a line feed, its blocks, a line feed, `{quote}` | the same | +| `bulletList`, `orderedList` | `* ` and `# `, one more mark per level, mixed as `#* ` and `*# `; an item holds a paragraph, then lists | also `- ` items, as `* ` | +| `codeBlock` with a `language` the help lists, one text node | `{code:java}`, a line feed, its text, a line feed, `{code}` | `{code}` reads `language` `java`, the help's default | +| `codeBlock` with no `language`, one text node | `{noformat}`, a line feed, its text, a line feed, `{noformat}` | the same | +| `panel` of `panelType` `info`, `note`, `tip`, `warning` | `{info}`, `{note}`, `{tip}`, `{warning}`, a line feed, its blocks, a line feed, the same macro | the same; a `title` parameter reads as the panel's first paragraph in `strong` | +| `rule` | `----` | the same | +| `table`, each cell one paragraph, a header row only first | `\|\|head\|\|`, then `\|cell\|` rows | the same | +| `mediaSingle`, centered, uncaptioned, holding an external `media` | `!url!`; `!url\|alt=text!` where it holds an `alt` with none of `!`, `\|`, `,` | the same | +| any other block node, a node of a type this version does not know | the carry | `{adf:display=block}` reads its node | + +## Inline + +| ADF | Wiki markup | Reader | +| --- | --- | --- | +| `text` | its text, a character wiki markup would read as markup where it stands taking a backslash; where a backslash cannot protect it, the run rides the inline carry | `\X` reads X | +| `hardBreak` | `\\` | the same | +| `mention` holding an `id` and no other attribute | `[~accountid:5b10ac8d82e05b22cc7d4ef5]` | the same; `[~name]` reads `id` `name` | +| any other inline node | the inline carry | `{adf:display=inline}` reads its nodes; `:)` and `:(` read `emoji` `:slight_smile:` and `:slight_frown:` | + +## Marks + +| ADF | Wiki markup | Reader | +| --- | --- | --- | +| `strong`, `em`, `strike`, `underline`, `code` | `*x*`, `_x_`, `-x-`, `+x+`, `{{x}}` | the same; `??x??` reads `em` | +| `subsup` | `^x^` for `sup`, `~x~` for `sub` | the same | +| `textColor` | `{color:#336699}x{color}` | the same; `{color:red}` reads `#ff0000` | +| `link` holding `href`, and `title` | `[text\|url]`, `[text\|url\|title]`; `[url]` where the text is the url | the same; `[#anchor]` and `[^name.ext]` read as targets `#anchor` and `^name.ext` | +| any other mark | the inline carry around the marked run | `{adf:display=inline}` reads its run | + +A mark wiki markup spells opens and closes beside a character that bounds it. A run whose edge +touches a word character, or whose delimiters the reader would read another way, rides the inline +carry. + +## What only the reader reads + +- `{anchor:name}` reads as nothing: no ADF node holds a bookmark. +- `{panel}` reads as a `panel` of `panelType` `info`, as the table says of a title; its colours and + border drop. +- `!name.ext!` reads as text: no ADF node holds an attachment by name. +- `---` and `--` read as `—` and `–`; `[file:///c:/temp/foo.txt]` reads as a `link`. +- A smiley other than `:)` and `:(` reads as text.