Markdown and Section Tags

Markdown is an interchange format for the body of a post. The saved content remains PageConfig.sections, with ordinary rich-text sections around illustrations, images and CTAs. Tags are expanded during import; they are not executed while rendering a published post.

Map tags to your catalogue

import {
  importArticleMarkdown,
  exportArticleMarkdown,
  type ArticleMarkdownOptions,
} from "@dollie_ai/editor";

const options = {
  prose: "article-prose",
  illustration: "article-illustration",
  image: "article-image",
  cta: "article-cta",
  illustrationIds: ["workflow-overview"],
} satisfies ArticleMarkdownOptions;

const result = importArticleMarkdown(markdown, options);
// Show result.issues to the author, then validate result.definition
// against the active catalogue before replacing or saving the body.
const exported = exportArticleMarkdown(result.definition, options);

The IDs above are examples: register those components yourself or substitute your own IDs. The mapping expects these props:

Section	Props
Prose	content (Markdown string)
Illustration	illustration (registered ID), optional caption
Image	src, optional alt and caption
CTA	title, label, href

A paragraph with **rich formatting**.

::illustration{id="workflow-overview" caption="How it works"}

Another paragraph.

::image{src="/images/example.jpg" alt="An example"}

::cta{title="Explore the product" label="Learn more" href="/product"}

Tags must occupy a standalone line. Attributes are unique, double-quoted JSON strings. Unknown illustration IDs, unknown attributes and malformed tags remain visible as prose and produce line-numbered issues. Inline tags and fenced examples are not expanded. Empty Markdown can produce an empty section list; retain a blank writing section when your post backend requires at least one body section.

The importer does not enforce safe URLs or host publication rules. Validate the resulting JSON, display import issues, and let your backend reject unresolved or incomplete content.

Insert at the caret

The optional RichTextFieldControl exposes an API through its onApi callback. splitAfterBlock() returns { before, after } Markdown around the top-level block containing the caret. It does not modify the document. A host can replace a writing section with the before-content, a newly inserted section, and the after-content in one undoable operation.

Export without losing content

Export only the body definition, not the BuilderDocument with its synthetic post header. Metadata such as title, tags and SEO does not belong in this Markdown format.

exportArticleMarkdown throws when it cannot preserve a component, structured property or section layout setting. For example, a customized illustration reference or section theme may require JSON export. Keep the original JSON and offer it as a lossless alternative.