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

Answer architecture round 1: the claims type pins what every writer spells, the HTML calls take flavour names, model-written GFM reads in portableMarkdownToAdf

This commit is contained in:
2026-10-09 02:42:55 +02:00
parent 859c952c93
commit 770be6be05
8 changed files with 52 additions and 19 deletions
+7 -7
View File
@@ -11,7 +11,8 @@ 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.
says, apart from raw HTML and the exceptions [The guarantees](#the-guarantees) lists; markdown
holding GFM's pipe tables or `~~` reads in `portableMarkdownToAdf`.
- **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.
@@ -19,7 +20,8 @@ products store as ADF.
save edits back, use the lossless pair.
- **No throws:** every call returns a result; a refusal carries a code from a closed list.
- **Runs anywhere:** pure functions with no runtime dependencies, in Node, Deno, Bun and browsers.
- **HTML at `0.3.0`:** `adfToHtml`, `htmlToAdf`, `markdownToHtml`, `htmlToMarkdown`.
- **HTML at `0.3.0`:** `adfToHtml`, `htmlToAdf`, and markdown to and from HTML through ADF, each
call named by its markdown flavour.
[The shape](#the-shape) · [Goals](#goals) · [Audience](#audience) ·
[Portable markdown](#portable-markdown) · [The errors](#the-errors) ·
@@ -49,8 +51,8 @@ if (result.ok) {
```
Serves [Goals](#goals) 1, 2 and 8. Pure functions, each taking a whole document and returning a
whole result; no I/O, no configuration. `markdownToHtml` and `htmlToMarkdown` convert through ADF:
they keep only what ADF holds, and refuse what `losslessMarkdownToAdf` or `htmlToAdf` refuses.
whole result; no I/O, no configuration. The `0.3.0` calls between markdown and HTML convert through
ADF: they keep only what ADF holds, and refuse what their markdown reader or `htmlToAdf` refuses.
```ts
adfToLosslessMarkdown(doc: AdfDocument): Result<string>
@@ -64,8 +66,6 @@ portableMarkdownToAdf(markdown: string): Result<AdfDocument, ParseError>
adfToHtml(doc: AdfDocument): Result<string> // 0.3.0
htmlToAdf(html: string): Result<AdfDocument, ParseError> // 0.3.0
markdownToHtml(markdown: string): Result<string> // 0.3.0
htmlToMarkdown(html: string): Result<string> // 0.3.0
```
`Result<T>` is `{ ok: true; value: T } | { ok: false; error: ConvertError }` — nothing throws.
@@ -170,7 +170,7 @@ stable across minors and safe to `switch` on exhaustively with no `default`; `me
and may change in any release. A parse always names a position, so the three markdown readers
return `ParseError`, whose `position` reads without a guard; an emit reads no
source and carries `path` alone; one handler typed on `ConvertError` takes both, which is what the
composed `markdownToHtml` and `htmlToMarkdown` hand back. `path` is the node's place from the
calls between markdown and HTML hand back. `path` is the node's place from the
document root, alternating `'content'` and an index, so `path.map((step) => '/' + step).join('')`
is a JSON Pointer at the node — the empty path being the document itself.