5.2 KiB
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 apanelofpanelTypeinfo, 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 alink.- A smiley other than
:)and:(reads as text.