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

Follow Jira's own reading and writing of panels and smileys in the wiki spec

This commit is contained in:
2026-11-17 00:41:15 +01:00
committed by Lillem4n
parent 29c519ac58
commit b5cc3610b4
2 changed files with 45 additions and 9 deletions
+15 -4
View File
@@ -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 ## 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 2026-11-16, a writer panel. Goal 11. Valid while a live Jira site renders each pick. Lands with
help doesn't show at all, `{note}`, a link's title, an image's `alt`, `\\` inside a cell, `spec/wiki.md`.
`[~accountid:<id>]` and `+x+` as underline, wait for the maintainer's check on a live site. Lands
with `spec/wiki.md`.
Atlassian's text formatting notation help is the source for every spelling it shows. Nine 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 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 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. 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:<id>]` 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=<colour>}`, 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:<language>}` reads
`java`.
## A plain wiki spelling stands for the attributes Jira's editor writes, and any other attribute rides the carry ## 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 2026-11-16, the implementer of the wiki spec; the maintainer confirmed on 2026-11-17 that `localId` and a
+30 -5
View File
@@ -41,7 +41,7 @@ string.
| `codeBlock` holding one text node, of `language` `""` or a name below in lowercase | `{code:<language>}`, a line feed, the text, a line feed, `{code}`; for `""`, `{noformat}`, the text, `{noformat}` the same way | the same, reading a `{code:<language>}` name in lowercase and `{noformat}` as `language` `""`; `{code}` reads `java`; `title`, `borderStyle` and the other panel parameters drop | | `codeBlock` holding one text node, of `language` `""` or a name below in lowercase | `{code:<language>}`, a line feed, the text, a line feed, `{code}`; for `""`, `{noformat}`, the text, `{noformat}` the same way | the same, reading a `{code:<language>}` 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 | | `heading` | `h1. ` to `h6. ` by `level` | the same |
| `mediaSingle` of `layout` `center`, holding one external `media` and no caption | `!<url>!`, or `!<url>\|alt=<alt>!` where `alt` holds none of `!`, `\|` and `,` | the same, reading `layout` `center`; `thumbnail`, `align` and the other parameters drop | | `mediaSingle` of `layout` `center`, holding one external `media` and no caption | `!<url>!`, or `!<url>\|alt=<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=<colour>}`, 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 | | `paragraph` holding content | its inline content | the same; a line feed in it reads as a `hardBreak`, as Jira renders it |
| `rule` | `----` | the same | | `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` | | `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 | | `hardBreak` | `\\` | the same |
| `mention` holding `id` and `accessLevel` `""`, and no other attribute | `[~accountid:<id>]` | the same, reading `accessLevel` `""`; `[~name]` reads as text, since Jira Cloud names a user by account id | | `mention` holding `id` and `accessLevel` `""`, and no other attribute | `[~accountid:<id>]` | 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` | | `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 ## 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 - An attribute with no spelling drops. A node whose type has none is its text, or its blocks where
it holds some. 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 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`. 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 - 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. - `{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. - `!name.ext!` reads as its text: no ADF node holds an attachment by name.
- `---` and `--` read as `—` and `–`. - `---` and `--` read as `—` and `–`.
- A smiley other than `:)` and `:(` reads as text: those two have an ADF name every emoji set - A smiley reads as the `emoji` Jira reads it as. `text` is the character where `id` is a code point,
shares, and the rest wait for a writer panel to pick one. 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` |