@avocadostudio-ai/richtext

The Avocado Studio rich-text grammar, and converters between it and the shapes three CMSes actually store.

No runtime dependencies, and no knowledge of React, the orchestrator or any CMS client — the CMS types are structural, so a one-off migration script can convert a dataset without installing anything else.

Two layers

The grammar (parse.ts) is the markdown subset an Avocado richtext string is written in — sized to exactly what the property panel's editor can produce, so anything a person can type comes back rendered rather than as punctuation. It is a parser only: it returns tokens, and what a heading or a link looks like on screen belongs to the calling surface.

The pivot (doc.ts) is a ProseMirror document — the shape the property panel edits natively. Every format converts to and from it rather than to and from each other, so a fourth CMS costs one converter pair instead of three.

Contentful ─┐                        ┌─ Contentful
Portable Text ├─→ RichTextDoc ─→ ─┤─ Portable Text
Strapi Blocks ─┤    (the pivot)     ├─ Strapi Blocks
markdown ──────┘                     └─ markdown

Converters

| CMS | in | out | | --- | --- | --- | | Avocado markdown | fromMarkdown | toMarkdown | | Sanity Portable Text | fromPortableText | toPortableText | | Contentful Rich Text | fromContentful | toContentful | | Strapi 5 Blocks | fromStrapiBlocks | toStrapiBlocks |

import { fromPortableText, toPortableText } from "@avocadostudio-ai/richtext"

// read
const doc = fromPortableText(sanityBlock.body)

// write — `previous` is what makes this an update rather than a replacement
const body = toPortableText(doc, { previous: storedBlock.body })

What survives

Node and mark type are open strings, not a union of the names we know. A Portable Text block with a custom _type, a Contentful embedded entry, a decorator some space enabled last week: none of them are in the vocabulary, and a closed type would force each converter to throw them away. They ride through the pivot as avocadoUnknownBlock carrying the source object under attrs.data and come back out unchanged.

Passing previous to toPortableText goes further: an unchanged block is re-emitted as the stored object itself, so keys, annotations and fields no converter here understands are preserved byte-for-byte, and the CMS sees a diff of what actually changed rather than "every block replaced".

mergeRichTextDoc(next, previous) is the same idea between two documents. It carries stored keys onto a rebuilt document and puts back the blocks the rebuild could not have contained — which is what makes it safe for the ops engine to parse a planner's plain-string rewrite into a document without deleting the embedded entry sitting in the middle of it.

What does not

Every format is missing something another one has, and the gaps are documented at each conversion rather than papered over:

• markdown has no underline and no way to name a CMS's own decorator. Those marks drop off in toMarkdown and the text stays. A value that needs them should be stored as a document, not flattened.
• markdown has no image in this grammar — the editor has no image node and deletes them — so an ![alt](src) keeps its alt text. Images belong in an f.image field.
• Contentful has no code block; code is a mark on text, so a code block becomes a code-marked paragraph.
• Portable Text and Strapi Blocks have no thematic break, so a horizontalRule is dropped rather than faked as a paragraph of dashes.
• Heading levels clamp to h2–h6 when flattening to markdown, because a page body never owns the page's h1. The document path does not clamp — that is the integration's outline, not ours.