3
0
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:
2026-10-09 02:49:10 +02:00
parent 6e2ac6040a
commit ba531e13bf
5 changed files with 26 additions and 14 deletions
+10 -7
View File
@@ -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 |