Fidelity and Unsupported Syntax

Leed Markdown has two readers. The published site renders it with markdown-it and a stack of Leed plugins; the CMS editor parses it into a ProseMirror document and writes it back out again. Those two implementations do not accept exactly the same language, and the site’s is the more permissive of the pair. Every entry on this page follows from that single fact — including the useful corollary that markdown which renders perfectly on your site can still fail to import.

The shape of a round trip

Markdown goes into the editor, becomes a ProseMirror document, lives as a collaborative Yjs document while anyone is editing it, and is serialized back to markdown when the page is published or read over MCP. Anything the ProseMirror schema does not model cannot survive that trip, because there is nowhere in the document for it to live.

flowchart LR
    MD["Leed Markdown"] --> P["parseMarkdownToProseMirror"]
    P --> Y["Y.Doc (collab-provider)"]
    Y --> S["serializeBodyToMarkdown"]
    S --> MD2["Leed Markdown"]
    MD --> R["markdown-it → published HTML"]

    P -.->|"raw HTML throws here"| PN["MarkdownParseError"]
    Y -.-> YN["anything the schema does not model is gone"]
    S -.-> SN["alignment, cell spans, tab-label attrs,<br/>extra embed params dropped; { } : @ escaped"]
    R -.-> RN["more permissive: renders things<br/>the editor cannot read back"]

    classDef note fill:none,stroke-dasharray:3 3;
    class PN,YN,SN,RN note;

The losses are therefore not arbitrary. They are all the same loss, observed at different places in one cycle.

What a save discards

The editor re-emits data-id and data-assetid plus the attributes each node type actually models, and nothing else. Everything below is dropped the first time a page is opened and saved — including a save triggered by an MCP edit.

That escape rule is the most confusing artifact you will meet in a round-tripped file. It is not corruption: the backslashes are there so the braces cannot be re-read as an attribute block on the next parse, and they do not appear in the rendered page.

What one layer has and the other does not

The three “editor only” rows in the middle are the collaboration layer, not content. They are supposed to disappear at publish time; nothing is lost when they do.

The alert row inverts this page’s lead, which is why it is worth reading twice: here the editor accepts more than the site does. The site registers its five containers by name, so a sixth name is simply not a container; the editor’s fence pattern captures any word and stores it, and there is no list of permitted types anywhere in the schema to reject it against. The failure is silent in both directions — a plain paragraph on the site, a colorless panel in the editor. Alerts enumerates the five that work.

Defects, not design

Three rows above are bugs rather than boundaries — the two layers disagree in a way neither one intends.

All three are tracked on Known Limitations, which is the page to check before you build a workaround — one of them may already be fixed.

Everything else on this page is a boundary rather than a defect: the editor models a document, and a document model is necessarily narrower than a text format.

Raw HTML

This is the sharpest edge in the format, and the one most likely to stop an import cold.

The published site renders arbitrary HTML verbatim. The editor’s parser cannot: the ProseMirror schema has no node for an HTML blob, so the parse throws rather than dropping the tag.

<br> is the sole exception.

If the HTML you need is structural — a two-column layout, a callout, a card — the Leed equivalents cover most of it: Alerts, Collapsible Sections, Tabs and Attributes between them replace most hand-written wrapper markup, and what remains usually belongs in a layout rather than in a page body.

Things Leed Markdown does not have

Two divergences that are neither loss nor bug

Bare URLs. The site renderer has link detection switched off; the editor’s parser has it on. So a bare URL that arrives through an import becomes a real link in the document — and then serializes back out as a real markdown link, at which point it works everywhere. One you type into a published file stays text. The behavior is inconsistent, but nothing is lost either way; the fix is to write links as links. Links and Internal Links covers the syntax.

Smart typography inside tab panels. Tab panels are rendered by a second markdown instance with the typographer disabled, so quotes, dashes and ellipses are converted outside a panel and left alone inside one. This is a rendering difference on the published page only; the stored markdown is identical either way. It is described in place on Tabs.

How to check your own content

Two checks catch nearly everything on this page, and both take a minute.

Diff what you sent against what came back. After any write, read the page back with get_page_markdown and compare it to the markdown you supplied. Every row in the discard table above shows up in that diff immediately, and the diff is the only reliable way to see them — nothing warns you at write time. Markdown for AI, MCP and Import covers the read-plan-apply loop this fits into.

Grep the built output for page-removed. A pageid: link whose target did not render in the build has its anchor replaced by a <span class="page-removed"> that keeps the link text, so a broken internal link looks completely normal on the page. Searching the built HTML for that class is how you find them.