mirror of
https://github.com/larvit/adf-codec.git
synced 2026-11-21 15:42:58 +01:00
Document the three markdown readers: README, MIGRATION, CHANGELOG, the grammar, the decisions and the plan
This commit is contained in:
+25
-20
@@ -2,8 +2,12 @@
|
||||
|
||||
## Unreleased
|
||||
|
||||
- **Breaking:** `markdownToAdf` and `plainMarkdownToAdf` refuse a value that is not a string with
|
||||
the new code `not-a-string`; `MIGRATION.md` lists what each value did before.
|
||||
- **Breaking:** each call names the markdown it reads or writes. `adfToMarkdown` and `markdownToAdf`
|
||||
are now `adfToLosslessMarkdown` and `losslessMarkdownToAdf`, and the new `commonMarkToAdf` reads
|
||||
markdown a person or a model wrote as the CommonMark spec says: a directive, a pipe table, `~~`
|
||||
and an `adf:` fence read as text and code. `MIGRATION.md` says which call to take.
|
||||
- **Breaking:** the markdown readers refuse a value that is not a string with the new code
|
||||
`not-a-string`; `MIGRATION.md` lists what each value did before.
|
||||
- **Breaking:** an attribute value that is not a plain object, array or JSON primitive, such as a
|
||||
`Date`, `Map`, typed array or class instance, makes `isAdfDocument` return `false` and the
|
||||
converters refuse it as `not-an-adf-document`. Before, the converters wrote it as `{}` or its own
|
||||
@@ -20,19 +24,20 @@
|
||||
- **Breaking:** the block carry is a code fence whose info string `adf:<type>` names the node's
|
||||
type, its body the node's JSON without `type`, and a code fence whose info string opens `adf:` is
|
||||
claimed, and `adf` is an ordinary code block language. Convert stored markdown per `MIGRATION.md`.
|
||||
- **Breaking:** `markdownToAdf` and `plainMarkdownToAdf` read markdown holding no block as a
|
||||
document whose `content` is empty, as Atlassian's schema requires; `!adf:doc {content=none}`
|
||||
spells a document holding no `content` key.
|
||||
- `markdownToAdf(adfToMarkdown(doc))` deep-equals `doc` as `JSON.parse` builds it: two adjacent text
|
||||
nodes CommonMark would read back as one are parted by `!adf:textBreak{}`, an empty `attrs`,
|
||||
`content` or `marks` is spelled `{attrs=empty}`, `{content=empty}` or `{marks=empty}`, `-0` is
|
||||
spelled `-0`, and a `codeBlock` of several text nodes is a fence per node. A `codeBlock` holding
|
||||
other than plain text nodes rides the block carry, where it was refused.
|
||||
- **Breaking:** the markdown readers read markdown holding no block as a document whose `content` is
|
||||
empty, as Atlassian's schema requires; `!adf:doc {content=none}` spells a document holding no
|
||||
`content` key.
|
||||
- `losslessMarkdownToAdf(adfToLosslessMarkdown(doc))` deep-equals `doc` as `JSON.parse` builds it:
|
||||
two adjacent text nodes CommonMark would read back as one are parted by `!adf:textBreak{}`, an
|
||||
empty `attrs`, `content` or `marks` is spelled `{attrs=empty}`, `{content=empty}` or
|
||||
`{marks=empty}`, `-0` is spelled `-0`, and a `codeBlock` of several text nodes is a fence per
|
||||
node. A `codeBlock` holding other than plain text nodes rides the block carry, where it was
|
||||
refused.
|
||||
- **Breaking:** `unspellable-character` and `unspellable-line-start` leave `ConvertErrorCode`, and
|
||||
`adfToMarkdown` no longer returns `unspellable-whitespace`. A carriage return in text is spelled
|
||||
` ` and a null character `!adf:text{text="\u0000"}`; a paragraph line opening with a code span
|
||||
is spelled as that code span, its backticks opening no fence; a code block holding either
|
||||
character, a code span holding a null character, a text node holding no text or holding
|
||||
`adfToLosslessMarkdown` no longer returns `unspellable-whitespace`. A carriage return in text is
|
||||
spelled ` ` and a null character `!adf:text{text="\u0000"}`; a paragraph line opening with a
|
||||
code span is spelled as that code span, its backticks opening no fence; a code block holding
|
||||
either character, a code span holding a null character, a text node holding no text or holding
|
||||
`content`, and an `emoji`, `mention` or `status` whose `text` holds a line ending or a null
|
||||
character ride the carry. See `MIGRATION.md`.
|
||||
- Fix a link `title` holding a null character: it is written as `!adf:link[text]{attrs}`, where it
|
||||
@@ -44,7 +49,7 @@
|
||||
`MIGRATION.md` lists each.
|
||||
- **Breaking:** a link whose text holds another link keeps the inner link and leaves the outer
|
||||
brackets literal text, where `0.1.0` split the outer link around it; see `MIGRATION.md`.
|
||||
- Add `adfToPlainMarkdown` and `plainMarkdownToAdf`, a lossy pair converting ADF to and from
|
||||
- Add `adfToPortableMarkdown` and `portableMarkdownToAdf`, a lossy pair converting ADF to and from
|
||||
markdown GitHub, GitLab and Obsidian render: alerts, callouts, task lists, `==highlights==` and
|
||||
pipe tables.
|
||||
- Spell `rule`'s `color`, `style` and `weight`, `layoutSection`'s `columnRuleStyle` and a link's
|
||||
@@ -52,12 +57,12 @@
|
||||
- Fix an image inside another image's description: it flattens into the alt text, where it was
|
||||
refused.
|
||||
- Fix a JSON key holding an escape, in a carried node or a JSON attribute such as `parameters`:
|
||||
`markdownToAdf` and `plainMarkdownToAdf` read it as the key it spells, where on V8 13.6 and later
|
||||
(Node 24, Deno, Chrome) they could refuse markdown `adfToMarkdown` wrote, as
|
||||
`unsupported-node-shape`, once the process had read a key holding a backslash
|
||||
`losslessMarkdownToAdf` reads it as the key it spells, where on V8 13.6 and later (Node 24, Deno,
|
||||
Chrome) `markdownToAdf` could refuse markdown `adfToMarkdown` wrote, as `unsupported-node-shape`,
|
||||
once the process had read a key holding a backslash
|
||||
([V8 bug](https://issues.chromium.org/issues/521080746)).
|
||||
- Fix a cyclic document, in which an object holds itself: `adfToMarkdown` and `adfToPlainMarkdown`
|
||||
refuse it as `not-an-adf-document` and `isAdfDocument` returns `false`, where all three hung.
|
||||
- Fix a cyclic document, in which an object holds itself: `adfToLosslessMarkdown` and
|
||||
`adfToPortableMarkdown` refuse it as `not-an-adf-document` and `isAdfDocument` returns `false`, where all three hung.
|
||||
|
||||
## 0.1.0
|
||||
|
||||
|
||||
Reference in New Issue
Block a user