mirror of
https://github.com/larvit/adf-codec.git
synced 2026-11-19 14:45:44 +01:00
Answer stability round 1: every reader names unsupported-nesting-depth, Flavour stays file-local; product-owner round 1: model markdown reads in portableMarkdownToAdf, the migration rows say what each reader builds, each code names its readers, item 84 filed
This commit is contained in:
@@ -10,9 +10,10 @@ products store as ADF.
|
||||
|
||||
- **Lossless:** `adfToLosslessMarkdown` and `losslessMarkdownToAdf` give back the document they
|
||||
started from — panels, mentions, statuses and node types this version does not know included.
|
||||
- **CommonMark in:** `commonMarkToAdf` reads a bot's or a model's markdown as the CommonMark spec
|
||||
says, apart from raw HTML and the exceptions [The guarantees](#the-guarantees) lists; markdown
|
||||
holding GFM's pipe tables or `~~` reads in `portableMarkdownToAdf`.
|
||||
- **Markdown in:** `portableMarkdownToAdf` reads a bot's or a model's markdown, GFM's pipe tables
|
||||
and `~~` included; `commonMarkToAdf` reads markdown known to be strict CommonMark as its spec
|
||||
says, nothing in it becoming a table, task or panel. Both apart from raw HTML and the exceptions
|
||||
[The guarantees](#the-guarantees) lists.
|
||||
- **Portable markdown, lossy:** `adfToPortableMarkdown` and `portableMarkdownToAdf` convert to and
|
||||
from the markdown that GitHub, GitLab and Obsidian render — GitHub Flavored Markdown's alerts,
|
||||
task lists and pipe tables, Obsidian Flavored Markdown's callouts and highlights.
|
||||
@@ -183,9 +184,11 @@ UTF-16 code unit, a JavaScript string index rather than a codepoint or a byte of
|
||||
or before the refusal — currently the start of the line the enclosing block begins on; a later
|
||||
minor may narrow that, never widen it. For `not-a-string` it is `{ line: 1, offset: 0 }`.
|
||||
|
||||
Parsing — `losslessMarkdownToAdf` raises every row, `portableMarkdownToAdf` the rows naming no
|
||||
directive, and `commonMarkToAdf` `not-a-string`, `unmappable-html` and `unmappable-image`;
|
||||
`htmlToAdf` at `0.3.0`:
|
||||
Parsing — `commonMarkToAdf` raises `not-a-string`, `unmappable-html` and `unmappable-image`;
|
||||
`portableMarkdownToAdf` those and `malformed-pipe-table`; `losslessMarkdownToAdf` every row; and
|
||||
`htmlToAdf`, at `0.3.0`, the rows its dialect reaches. Every reader also raises
|
||||
`unsupported-nesting-depth`, and `losslessMarkdownToAdf` `unsupported-node-shape`, from the table
|
||||
after next:
|
||||
|
||||
| Code | Fires when | What you can do |
|
||||
| --- | --- | --- |
|
||||
@@ -193,7 +196,7 @@ directive, and `commonMarkToAdf` `not-a-string`, `unmappable-html` and `unmappab
|
||||
| `malformed-pipe-table` | a pipe row that is no pipe table — a missing or ragged `---` delimiter row, an alignment colon in it, or a row not opening with a pipe | open every row with a pipe and give the delimiter row the header's cell count; to keep the lines literal text instead, escape the leading pipe of every one — escaping a single row leaves the next to open a fresh table and fail the same way |
|
||||
| `not-a-string` | the value handed in is not a string, such as `null`, a number or a `String` object | pass the input as a string, `String(value)` for a `String` object; the message names the value's type |
|
||||
| `unknown-directive-name` | a directive whose name is no node or mark this version spells | check the name in `spec/flavour.md`, or escape the prefix as `\!adf:`; the spelling itself is well formed, so a later minor may give the name meaning |
|
||||
| `unmappable-html` | the input holds an HTML construct the documented element set does not map, a comment and a processing instruction among them — at this version that is every raw HTML construct in markdown, the element set landing at `0.3.0` | remove the construct, or write what it holds in the lossless flavour |
|
||||
| `unmappable-html` | the input holds an HTML construct the documented element set does not map, a comment and a processing instruction among them — at this version that is every raw HTML construct in markdown, the element set landing at `0.3.0` | remove the construct, or write what it holds as markdown |
|
||||
| `unmappable-image` | an image sits inside other content that is not another image's description, or carries a title | give the image a paragraph of its own and drop the title |
|
||||
| `unspellable-whitespace` | an `emoji`, `mention` or `status` directive's content slot spells a newline or a carriage return — ` `, ` `, `!adf:text{text="\n"}` | replace it with a space, or write the node as `!adf:carry` — an inline directive never spans lines |
|
||||
|
||||
|
||||
Reference in New Issue
Block a user