3
0
mirror of https://github.com/larvit/adf-codec.git synced 2026-11-19 06:35:44 +01:00
Files
adf-codec/spec/wiki.md
T

162 lines
11 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Jira wiki markup
What `adfToLosslessJiraWiki`, `adfToLossyJiraWiki` and the Jira wiki markup reader do with each ADF
node and mark. Each table's middle column is what both writers write, and the last is what the
reader reads; "The lossy writer" says where the lossy writer differs. The source is Atlassian's
"Text Formatting Notation Help", which Jira serves at `/secure/WikiRendererHelpAction.jspa?section=all`.
A spelling the help doesn't show is what a live Jira site reads and writes, else a writer panel's
pick, per `docs/decisions.md` §Jira wiki markup spellings the help leaves open are a writer panel's
picks. The written form is contract
(`docs/decisions.md` §The formats are API).
## The carry
Wiki markup has no spelling for some nodes, marks and attributes. The lossless writer writes each
such node as Jira's own `{adf}` macro around the node's ADF JSON, per `docs/decisions.md` §Jira wiki
markup carries what it cannot spell in Jira's `{adf}` macro, and a lossy writer keeps only its
content:
- A block node: `{adf:display=block}`, a line feed, the JSON, a line feed, `{adf}`.
- An inline node: `{adf:display=inline}`, the node's JSON, `{adf}`. The run of inline nodes under a
mark with no spelling is one such macro per node, since Jira reads a node and never an array there.
The JSON is compact with its keys sorted, as `spec/flavour.md` writes the markdown carry's, and a
`{` inside a string is `\u007b`, so the closing `{adf}` is the only one the text holds. A document
holding no `content` key rides whole, as a block.
A node rides the carry when it, one of its attributes or one of its marks has no spelling below. It
also rides when it holds a block or inline node that rides, except that a node that rides inside a
paragraph stands on its own there, in the paragraph's text. A block that rides inside a list item or
a table cell makes the list or the table ride instead, since wiki markup can't hold a block macro
there. A `blockquote` written as `{quote}` that holds another at any depth rides, as does a `panel`
holding another `panel` at any depth, since a macro can't nest in its own kind. Any `localId` rides, since `docs/decisions.md`
§Ids stay site-local keeps ids in attributes.
## Blocks
Below, a markup character is a backslash, a bracket, a brace or `|`. Blocks are parted by one blank
line. A document whose `content` is an empty array is the empty
string.
| ADF | Wiki markup | Reader |
| --- | --- | --- |
| `blockquote` holding one paragraph | `bq. `, the paragraph | the same |
| `blockquote`, any other | `{quote}`, a line feed, its blocks, a line feed, `{quote}` | the same |
| `bulletList`, `orderedList` of `order` 1, its items each a paragraph then lists | `* ` and `# `, one more character per level, nested lists mixed as `#* ` and `*# ` | the same, and `- ` items as `* `; an `orderedList` reads `order` 1 |
| `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 |
| `mediaSingle` of `layout` `center`, holding one external `media` and no caption | `!<url>!`, or `!<url>\|alt=<alt>!` where `alt` isn't empty, holds no markup character, `!`, `,`, line feed or carriage return, and doesn't start or end with whitespace; a `url` that is empty or holds whitespace, `!` or a markup character rides the carry | the same, reading `layout` `center`; `thumbnail`, `align` and the other parameters drop |
| `panel` of `panelType` `error`, `info`, `note`, `success` or `warning` | `{panel:bgColor=<colour>}`, a line feed, its blocks, a line feed, `{panel}`, the colour being `#ffebe6` for `error`, `#deebff` for `info`, `#eae6ff` for `note`, `#e3fcef` for `success` and `#fffae6` for `warning` | 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`, colours compared without case; the other parameters drop |
| `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` |
| any other block node, including a `paragraph` holding no content or only whitespace outside a table cell, and a node of a type this version doesn't know | the carry | `{adf:display=block}` reads its node |
The names the help lists for a `codeBlock`: actionscript, ada, applescript, bash, c, c#, c++, css,
erlang, go, groovy, haskell, html, java, javascript, json, lua, nyan, objc, perl, php, python, r,
ruby, scala, sql, swift, visualbasic, xml and yaml. A `codeBlock` with any other `language`, none
included, or a text holding `{code}` or `{noformat}`, rides the carry.
A value other than the one a table names, an absent attribute included, rides the carry: so does
a `width`, a merged cell and a colour.
## Inline
| ADF | Wiki markup | Reader |
| --- | --- | --- |
| `hardBreak` | `\\` | the same |
| `mention` holding `id` and `accessLevel` `""`, and no other attribute, the `id` not empty and holding no whitespace or markup character | `[~accountid:<id>]` | the same, reading `accessLevel` `""`; `[~name]` reads as text, since Jira Cloud names a user by account id |
| `text` | its text, escaped as below | `\\` 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 node |
A character takes a backslash where wiki markup would read it as markup. Here a line's edge counts
as whitespace, and a node's edge inside the line as punctuation:
- `[`, `]`, `{`, `}` and `|`, always, except that a `|` in a table cell rides the carry, since an
escaped one still ends the cell.
- `*`, `+`, `-`, `^`, `_` and `~`, unless a letter or digit stands on both sides, or whitespace
does.
- `?` before another `?`, and `!` before anything but whitespace.
- The `(` of a smiley listed under What only the reader reads, or the closing `)` of one that starts
with `:` or `;`, where no letter or digit follows the smiley, or where the node's edge cuts it
inside the line.
- At a line's start, `#`, `*` and `-`.
Jira keeps a backslash before `:`, `;`, a letter or a digit as text. So no backslash protects a
backslash, a line feed or a carriage return; `http://` or `https://` in any case, which Jira would
link; the `h` of `h1.` to `h6.` or the `b` of `bq.` at a line's start, in any case; `:D` and `:P`;
or a `:` or `;` ending a node inside the line, where the next node's spelling may close a smiley. A
text holding one rides the carry. So does a text that starts or ends its line with whitespace, and
a text whose marks are those of the text before it, which the reader would join. A `hardBreak` or
`mention` holding a mark rides too.
## Marks
| ADF | Wiki markup | Reader |
| --- | --- | --- |
| `code`, `em`, `strike`, `strong`, `underline` | `{{x}}`, `_x_`, `-x-`, `*x*`, `+x+` | the same; `??x??` reads `em` |
| `link` holding `href` | `[<text>\|<href>]`, with `\|<title>` after the `href` where it holds a `title`; `[<href>]` where the link is the text's last mark, the text is the `href`, the link marks neither neighbour and holds no `title`, and the `href` doesn't start with `~`; an `href` that is empty or holds whitespace or a markup character rides the carry, as does a `title` that is empty, holds a markup character, a line feed or a carriage return, or starts or ends with whitespace | the same; `[#anchor]` and `[^name.ext]` read as `href` `#anchor` and `^name.ext` |
| `subsup` | `^x^` for `sup`, `~x~` for `sub` | the same |
| `textColor` | `{color:<hex>}x{color}` | the same; a CSS colour name reads as its hex code, so `red` as `#ff0000` |
| any other mark | the carry of each node of the marked run | `{adf:display=inline}` reads its node |
Marks nest in the order the node's array holds them, outermost first, and a run of nodes sharing
their outermost mark shares its delimiters. The delimiters of `code`, `em`, `strike`, `strong`,
`subsup` and `underline` each need whitespace, punctuation or the line's edge outside them, and no
whitespace inside them. A run where one fails rides the carry whole, as does a node holding two marks
of one type.
## The lossy writer
The lossy writer writes no `{adf}`. It writes the plain spellings above, and for what the lossless
writer carries it keeps the content, as `docs/decisions.md` §Plain text is blocks a blank line apart
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
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
help doesn't list is `{noformat}`, and one whose text holds `{code}` or `{noformat}` is a
paragraph of its lines parted by `\\`.
- A stored `media` is its `alt`, else `[image]`.
- A mark with no spelling drops, keeping its text.
## What only the reader reads
The writers never write these, and the reader reads them as follows:
- `{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 reads as the `emoji` Jira reads it as, wherever the next character is not a letter or a
digit and whatever comes before it: `x:)` and `f(x)` read, `a:Pb` and `:)x` don't, and a backslash
before its `(` or its closing `)` stops it: `\(y)` and `:\)` read as text. The `emoji`'s `text` is the character where its `id` is a code point, else its
`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` |