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

83 lines
5.2 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
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.