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

Spec each node's and mark's Jira wiki spelling and record the writers' names and the panel picks

This commit is contained in:
2026-11-16 23:22:37 +01:00
committed by Lillem4n
parent 89d0847e19
commit 17237510e1
3 changed files with 116 additions and 0 deletions
+2
View File
@@ -95,6 +95,8 @@ In `docs/decisions.md`:
- The feature table is a section per corpus example, led by a summary table
- Plain text is blocks a blank line apart, with `• ` and `1.` markers and nesting indented
- Jira wiki markup carries what it cannot spell in Jira's `{adf}` macro, and a lossy writer keeps only its content
- Jira wiki markup's writers are `adfToLosslessJiraWiki` and `adfToLossyJiraWiki`, two calls with no option
- Jira wiki markup spellings the help leaves open are a writer panel's picks
- `htmlToAdf` reads any HTML, with no option and no second call
## 1. Nothing about any consumer in the library
+32
View File
@@ -1457,6 +1457,38 @@ block node, `{adf:display=inline}` for an inline node or a marked run. The round
Jira still renders the document. The lossy wiki writer ships beside it for consumers who want wiki
markup alone: it drops the form of what wiki markup cannot spell and keeps its content.
Confirmed 2026-11-16 on a live Jira Cloud site: a description holding `{adf:display=block}` around
a `table` node's JSON rendered a table, and `{adf:display=inline}` around a `status` node's JSON
rendered the status lozenge between its neighbouring words.
## Jira wiki markup's writers are `adfToLosslessJiraWiki` and `adfToLossyJiraWiki`, two calls with no option
2026-11-16, a developer panel. Goals 6, 7 and 8. Valid while a lossy writer drops form with no
refusal. Lands with `todo.md` items 193 to 196.
Seven fresh-context readers, seated as the bot, the viewer/editor app and the LLM pipeline, were
told the trap: an app saving through the lossy writer loses form on every save, with nothing
refused. All seven picked `adfToLosslessJiraWiki` and `adfToLossyJiraWiki` as two calls over one
call with `{ lossy: true }`, and over `adfToPortableWiki`, which reads as the safe choice. The
reader's name is not settled in this entry: the seats split four to three between
`jiraWikiMarkupToAdf` and `jiraWikiToAdf`, short of five of seven.
## 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 ones its
help does not show, `{note}`, a link's title, an image's `alt`, `\\` inside a cell and
`[~accountid:…]`, wait for the maintainer's check there. Lands with `spec/wiki.md`.
Atlassian's text formatting notation help is the source for every spelling it shows. For the nine
it leaves open, seven fresh-context readers, seated as wiki-markup authors, each wrote their own
spelling before picking among shuffled candidates, with no rationale and nothing saying what is
implemented. Seven agreed on a one-paragraph blockquote as `bq. `, any other as `{quote}`, a note
panel as `{note}`, underline as `+x+`, a mention as `[~accountid:5b10ac8d82e05b22cc7d4ef5]` and a
cell's two paragraphs as `\\`. Six picked `{noformat}` over `{code:none}` for a code block with no
language, five `[text|url|title]` over dropping the title, five `alt=text` over `alt="text"`. The
first three seats read the brief's first 60 lines, which held a few of its first question's
candidates; the last four read 55.
## `htmlToAdf` reads any HTML, with no option and no second call
2026-11-15, a developer panel. Goals 6, 8 and 12. Valid while the dialect and foreign HTML read
+82
View File
@@ -0,0 +1,82 @@
# 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.