From b5cc3610b4be38bab09ae4ac38db46ef21d0c01e Mon Sep 17 00:00:00 2001 From: Lilleman auf Larv Date: Tue, 17 Nov 2026 00:41:15 +0100 Subject: [PATCH] Follow Jira's own reading and writing of panels and smileys in the wiki spec --- docs/decisions.md | 19 +++++++++++++++---- spec/wiki.md | 35 ++++++++++++++++++++++++++++++----- 2 files changed, 45 insertions(+), 9 deletions(-) diff --git a/docs/decisions.md b/docs/decisions.md index 81bbbb0..12aebf0 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -1478,10 +1478,8 @@ to three between it and `jiraWikiMarkupToAdf`, short of the five of seven that s ## 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 picks the -help doesn't show at all, `{note}`, a link's title, an image's `alt`, `\\` inside a cell, -`[~accountid:]` and `+x+` as underline, wait for the maintainer's check on a live site. Lands -with `spec/wiki.md`. +2026-11-16, a writer panel. Goal 11. Valid while a live Jira site renders each pick. Lands with +`spec/wiki.md`. Atlassian's text formatting notation help is the source for every spelling it shows. Nine spellings it leaves open went to seven fresh-context readers, seated as wiki-markup authors. Each @@ -1493,6 +1491,19 @@ language, five `[text|url|title]` over dropping the title, and five `alt=text` o The first three readers saw a few of the first question's candidates among the brief's opening lines, before they wrote their own; the last four did not. +Checked 2026-11-17 on the maintainer's Jira Cloud test site, by writing each spelling as wiki +markup through its v2 API and reading back the ADF it became, and the reverse. Jira reads +`\\` inside a cell as a `hardBreak`, `[~accountid:]` as a `mention`, `+x+` as `underline`, +`alt=text` as the image's `alt`, a link's `|title` without error but drops the title, and a smiley +as the `emoji` `spec/wiki.md` lists. It doesn't read `{note}`, `{info}`, `{tip}` or `{warning}`: they +stay text. A panel is `{panel:bgColor=}`, which Jira reads and writes, one colour a type: +`info`, `note`, `success`, `warning` and `error`. Jira writes `tip` with an empty colour and reads +that back as `info`, so `tip` rides the carry. That overturns the panel's `{note}` pick, and +`spec/wiki.md` follows Jira. Jira differs from the spec where the spec keeps its own reading: +`[~name]` reads as a `mention` with `id` `unknown`, `??x??` as `em` prefixed by `— `, header cell +text carries `strong`, `{noformat}` has no `language`, and an unknown `{code:}` reads +`java`. + ## A plain wiki spelling stands for the attributes Jira's editor writes, and any other attribute rides the carry 2026-11-16, the implementer of the wiki spec; the maintainer confirmed on 2026-11-17 that `localId` and a diff --git a/spec/wiki.md b/spec/wiki.md index 764d6a4..bb3f107 100644 --- a/spec/wiki.md +++ b/spec/wiki.md @@ -41,7 +41,7 @@ string. | `codeBlock` holding one text node, of `language` `""` or a name below in lowercase | `{code:}`, a line feed, the text, a line feed, `{code}`; for `""`, `{noformat}`, the text, `{noformat}` the same way | the same, reading a `{code:}` name in lowercase and `{noformat}` as `language` `""`; `{code}` reads `java`; `title`, `borderStyle` and the other panel parameters drop | | `heading` | `h1. ` to `h6. ` by `level` | the same | | `mediaSingle` of `layout` `center`, holding one external `media` and no caption | `!!`, or `!\|alt=!` where `alt` holds none of `!`, `\|` and `,` | the same, reading `layout` `center`; `thumbnail`, `align` and the other parameters drop | -| `panel` of `panelType` `info`, `note`, `tip` or `warning` | the macro of that name, a line feed, its blocks, a line feed, the macro | the same; a `title` parameter reads as the panel's first paragraph in `strong`; `{panel}` reads as `info` | +| `panel` of `panelType` `info`, `note`, `success`, `warning` or `error` | `{panel:bgColor=}`, a line feed, its blocks, a line feed, `{panel}`, the colour being `#deebff`, `#eae6ff`, `#e3fcef`, `#fffae6` or `#ffebe6` in that order | the same; a `title` parameter reads as the panel's first paragraph in `strong`; `{panel}` and any `bgColor` the five spellings leave out read as `info` | | `paragraph` holding content | its inline content | the same; a line feed in it reads as a `hardBreak`, as Jira renders it | | `rule` | `----` | the same | | `table` of `isNumberColumnEnabled` `false` and `layout` `default`, plain rows, each cell holding one paragraph | per cell, `\|\|` for a `tableHeader` and `\|` for a `tableCell`, then its paragraph, the row closed by the last cell's delimiter; an empty paragraph as a space | the same; a space-only cell reads as an empty paragraph, and a whitespace-only text rides the carry; reads `isNumberColumnEnabled` `false` and `layout` `default` | @@ -62,7 +62,7 @@ a `width`, a merged cell and a colour. | `hardBreak` | `\\` | the same | | `mention` holding `id` and `accessLevel` `""`, and no other attribute | `[~accountid:]` | the same, reading `accessLevel` `""`; `[~name]` reads as text, since Jira Cloud names a user by account id | | `text` | its text; a character wiki markup would read as markup where it stands takes a backslash, and a text no backslash protects, such as a backslash itself or a URL Jira would link, rides the carry | `\\` reads as a `hardBreak` before `\X` reads `X`; a bare `http://` or `https://` address reads as a `link` | -| any other inline node | the carry | `{adf:display=inline}` reads its nodes; `:)` and `:(` read `emoji` `:slight_smile:` and `:slight_frown:` | +| any other inline node | the carry | `{adf:display=inline}` reads its nodes; a smiley in the table under "What only the reader reads" reads as that `emoji` | ## Marks @@ -85,7 +85,7 @@ says `adfToPlainText` does, in wiki markup: - An attribute with no spelling drops. A node whose type has none is its text, or its blocks where it holds some. -- A `panel` of another type is `{panel}`. An `expand` is its title as a `*strong*` paragraph, then +- A `panel` of type `tip` is `{panel}`. An `expand` is its title as a `*strong*` paragraph, then its body. A task item is `* `, then `☑ ` or `☐ ` and its text. A `status`, `date` and `emoji` are the text they show, and a `mention` that rides is its `text`. - A `table` cell holding several blocks has them parted by `\\`; a `codeBlock` with a language the @@ -101,5 +101,30 @@ Each of these has no ADF counterpart, so the reader keeps the text where there i - `{anchor:name}` reads as nothing, since no ADF node holds a bookmark. - `!name.ext!` reads as its text: no ADF node holds an attachment by name. - `---` and `--` read as `—` and `–`. -- A smiley other than `:)` and `:(` reads as text: those two have an ADF name every emoji set - shares, and the rest wait for a writer panel to pick one. +- A smiley reads as the `emoji` Jira reads it as. `text` is the character where `id` is a code point, + else the `shortName`. + + | Smiley | `shortName` | `id` | + | --- | --- | --- | + | `:)` | `:slight_smile:` | `1f642` | + | `:(` | `:disappointed:` | `1f61e` | + | `:P` | `:stuck_out_tongue:` | `1f61b` | + | `:D` | `:smiley:` | `1f603` | + | `;)` | `:wink:` | `1f609` | + | `(y)` | `:thumbsup:` | `1f44d` | + | `(n)` | `:thumbsdown:` | `1f44e` | + | `(i)` | `:info:` | `atlassian-info` | + | `(/)` | `:check_mark:` | `atlassian-check_mark` | + | `(x)` | `:cross_mark:` | `atlassian-cross_mark` | + | `(!)` | `:warning:` | `atlassian-warning` | + | `(+)` | `:plus:` | `atlassian-plus` | + | `(-)` | `:minus:` | `atlassian-minus` | + | `(?)` | `:question:` | `atlassian-question_mark` | + | `(on)` | `:light_bulb_on:` | `atlassian-light_bulb_on` | + | `(off)` | `:light_bulb_off:` | `atlassian-light_bulb_off` | + | `(*)` and `(*y)` | `:yellow_star:` | `atlassian-yellow_star` | + | `(*r)` | `:red_star:` | `atlassian-red_star` | + | `(*g)` | `:green_star:` | `atlassian-green_star` | + | `(*b)` | `:blue_star:` | `atlassian-blue_star` | + | `(flag)` | `:flag_on:` | `atlassian-flag_on` | + | `(flagoff)` | `:flag_off:` | `atlassian-flag_off` |