diff --git a/MIGRATION.md b/MIGRATION.md index 2dc0d2b..f9b9b49 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -6,7 +6,8 @@ Directives moved under the `!adf:` prefix. `0.2.0` reads `0.1.0`'s spelling with 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 no change. +the tables below. Stored ADF needs one change: a document `0.1.0` read from empty markdown holds +no `content` key, and gets `content: []`, the empty document it meant. ### Convert markdown @@ -30,8 +31,9 @@ function migrateMarkdown(stored: string) { - Convert each document once: a second pass can return ok while turning the directives into text. Stop `0.1.0` writing first, and record which documents are converted. - A refusal carrying `position` is `0.1.0`'s parse, which refused that markdown before too. One - without is `0.2.0`'s emit: store the document `markdownToAdf010` read as ADF rather than keeping - the unconverted markdown. + without is `0.2.0`'s emit: store the document `markdownToAdf010` read as ADF, with + `content: parsed.value.content ?? []` as the recipe gives it, rather than keeping the unconverted + markdown. ### Spellings @@ -56,7 +58,7 @@ Markdown the spelling table leaves alone, which `0.2.0` reads as a different doc | --- | --- | --- | | a link whose text already holds one (`[ab](/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; write `!adf:codeBlock {language="adf:x"}` around a bare fence to keep the code block | +| 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 | ### Error codes