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

5.2 KiB
Raw Blame History

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.