adf-codec/MIGRATION.md

Migrating

From 0.1.0 to 0.2.0

Directives moved under the !adf: prefix. 0.2.0 reads markdown 0.1.0 wrote without an error and turns every directive in it into plain text, so convert stored markdown before 0.2.0 reads it. Stored ADF needs no change.

Convert stored markdown

Read it with 0.1.0 and write it with 0.2.0, installed side by side:

npm install @larvit/adf-codec@0.2.0 adf-codec-0.1@npm:@larvit/adf-codec@0.1.0

import { adfToMarkdown } from '@larvit/adf-codec'
import { markdownToAdf as markdownToAdf010 } from 'adf-codec-0.1'

function migrateMarkdown(stored: string) {
  const parsed = markdownToAdf010(stored)
  return parsed.ok ? adfToMarkdown(parsed.value) : parsed
}

Spellings

0.1.0	0.2.0
:::panel info … :::, the fence longer per nesting level	!adf:panel info … !adf:/panel at any depth
::media {id=a type=file}	!adf:media {id=a type=file}
::paragraph, the empty paragraph	!adf:paragraph then !adf:/paragraph
:mention[@Mikael]{id=5b10a2}	!adf:mention[@Mikael]{id=5b10a2}
the adf code fence and :adf{json="…"}	the carry code fence and !adf:carry{json="…"}
\: keeps a directive literal	\!adf: keeps a directive literal

A colon run and :name[ are plain text now, and adf is an ordinary code block language.

Error codes

Input	0.1.0	0.2.0
a leaf node given a body, listBreak included: :::media {…} … :::, !adf:media {…} … !adf:/media	unsupported-node-shape	malformed-directive
a container node with no closer: ::panel info, !adf:panel info	unsupported-node-shape	malformed-directive
an empty paragraph with a closer: :::paragraph … :::, !adf:paragraph … !adf:/paragraph	unsupported-node-shape	parses