3
0
mirror of https://github.com/larvit/adf-codec.git synced 2026-11-20 07:05:44 +01:00

Document the three markdown readers: README, MIGRATION, CHANGELOG, the grammar, the decisions and the plan

This commit is contained in:
2026-10-09 02:36:06 +02:00
parent 9ce5dfa01b
commit 80692f34ed
8 changed files with 235 additions and 224 deletions
+20 -12
View File
@@ -2,12 +2,20 @@
## From `0.1.0` to `0.2.0`
Directives moved under the `!adf:` prefix. `0.2.0` reads `0.1.0`'s spelling without an error,
turning each directive into text and each carried node into an `adf` code block. Before `0.2.0`
reads any `0.1.0` markdown, convert what is stored or in flight (an open editor, a queue) with the
recipe below, and rewrite markdown your code writes or matches (templates, prompts, patterns) by the
tables below. Stored ADF needs one change: give a document holding no `content` key `content: []`.
`0.1.0` built that shape from empty markdown, meaning the empty document.
Each call names the markdown it reads or writes:
| `0.1.0` | `0.2.0` |
| --- | --- |
| `adfToMarkdown` | `adfToLosslessMarkdown` |
| `markdownToAdf`, for markdown `adfToMarkdown` wrote | `losslessMarkdownToAdf` |
| `markdownToAdf`, for markdown a person or a model wrote | `commonMarkToAdf`, which reads a directive, a pipe table, `~~` and an `adf:` fence as CommonMark does, as text and code |
Directives moved under the `!adf:` prefix. `losslessMarkdownToAdf` reads `0.1.0`'s spelling without
an error, turning each directive into text and each carried node into an `adf` code block. Before
`0.2.0` reads any `0.1.0` markdown, convert what is stored or in flight (an open editor, a queue)
with the recipe below, and rewrite markdown your code writes or matches (templates, prompts,
patterns) by the tables below. Stored ADF needs one change: give a document holding no `content` key
`content: []`. `0.1.0` built that shape from empty markdown, meaning the empty document.
### Convert markdown
@@ -18,13 +26,13 @@ npm install @larvit/adf-codec@0.2.0 adf-codec-0.1@npm:@larvit/adf-codec@0.1.0
```
```ts
import { adfToMarkdown } from '@larvit/adf-codec'
import { adfToLosslessMarkdown } from '@larvit/adf-codec'
import { markdownToAdf as markdownToAdf010 } from 'adf-codec-0.1'
function migrateMarkdown(stored: string) {
const parsed = markdownToAdf010(stored)
// 0.1.0 dropped an empty content array, so a document with no content key meant an empty one.
return parsed.ok ? adfToMarkdown({ ...parsed.value, content: parsed.value.content ?? [] }) : parsed
return parsed.ok ? adfToLosslessMarkdown({ ...parsed.value, content: parsed.value.content ?? [] }) : parsed
}
```
@@ -57,15 +65,15 @@ Markdown the spelling table leaves alone, which `0.2.0` reads as a different doc
| Input | `0.1.0` | `0.2.0` |
| --- | --- | --- |
| a link whose text already holds one (`[a<https://example.com/>b](/v)`) | marks every node the inner link does not, splitting the outer link around it | leaves the outer brackets literal text; write the pieces as separate links to keep them |
| markdown holding no block (`markdownToAdf("")`) | `{ type: 'doc', version: 1 }` | `{ content: [], type: 'doc', version: 1 }`; `!adf:doc {content=none}` reads as the former |
| a code fence whose info string opens `adf:` (```` ```adf:x ````) | a `codeBlock` with that language | the block carry, refusing a body that is not one node's canonical JSON; write `!adf:codeBlock {language="adf:x"}` around a bare fence to keep the code block |
| markdown holding no block (`""`) | `{ type: 'doc', version: 1 }` | `{ content: [], type: 'doc', version: 1 }`; `!adf:doc {content=none}` reads as the former |
| a code fence whose info string opens `adf:` (```` ```adf:x ````) | a `codeBlock` with that language | in `losslessMarkdownToAdf`, the block carry, refusing a body that is not one node's canonical JSON; write `!adf:codeBlock {language="adf:x"}` around a bare fence to keep the code block |
### Error codes
`unspellable-character`, `unspellable-line-start` and `unspellable-link` leave `ConvertErrorCode`
and `not-a-string` joins it: a `switch` naming one of the three stops compiling, and one naming
every code needs the new case. A document `adfToMarkdown` refused with one of the three now
converts; markdown the parser refused with one of the three now refuses with the code the table
every code needs the new case. A document `adfToMarkdown` refused with one of the three
`adfToLosslessMarkdown` now converts; markdown the parser refused with one of the three now refuses with the code the table
gives.
| Input | `0.1.0` | `0.2.0` |