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. The two share one parser for every Leed construct, but the editor stores a document, and a document can hold less than a text format can. Every entry on this page follows from that single fact — including the corollary that markdown which renders perfectly from a template can come back from a CMS page body changed. What changes is now always reported, and it changes only once.

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 kept as text"| PN["comments stripped, ids dropped"]
    Y -.-> YN["anything the schema does not model is gone"]
    S -.-> SN["extra cell keys and embed params dropped;<br/>{ } escaped"]
    R -.-> RN["template Markdown can use<br/>what a page body cannot store"]

    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 or rewritten the first time a page is opened and saved — including a save triggered by an MCP edit. That first save is also the last change: the stored body is a fixed point, so a second save, a read over MCP or a publish changes nothing further, and the site renders the stored body exactly as the editor reads it. Nothing is lost silently either: a write reports every row below that loses content as dropped — a lost line or part of one under dropped_content, a stripped attribute group under dropped_attributes.

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, and a leading marker cannot be re-read as a block, on the next parse. 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 is worth reading twice: both layers accept any type name, and neither checks it against a list. The site renders an unknown type as an aside with the class alert-<type>, and the editor stores it and writes it back unchanged — but only the five types Alerts lists come with an icon and theme colors. Any other name is a plain panel until your own CSS styles it.

Defects, not design

One behavior is a bug rather than a boundary — the two layers disagree in a way neither one intends.

It is tracked on Known Limitations, which is the page to check before you build a workaround — it may already be fixed. Two defects were on this list until they were fixed: a numbered list that published from 1 whatever its start was, which the editor now writes natively (14. Item), and table column alignment, which was flattened on the first save and is now kept, along with cell spans and classes. Tables has the form the editor writes them in.

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. Raw HTML no longer stops an import, but it does not survive one as HTML either.

The published site renders HTML written in a template verbatim. A CMS page body cannot hold it: the ProseMirror schema has no node for an HTML blob, so the editor keeps the tag as literal text — escaped, so that it reads back as the same text — and the published page shows it exactly as typed.

<br> is the only tag that becomes structure. Inside a code span or a fence, HTML and comments are code and are kept as written.

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

Divergences that are neither loss nor bug

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.

Glyph swaps on the site. Outside a tab panel, the site’s typographer swaps some characters for display: straight quotes become curly quotes (“”, ‘’), -- and --- become – and —, (c), (r) and (tm) in either case become ©, ® and ™ (so their case is lost), +- becomes ±, and exactly three dots become …. It never drops a character you wrote: !!!!, ????, ,,, .. and .... render as written, and ?... renders as ?…. The editor and the CTA settings editor store and show text exactly as typed, so the stored markdown never changes.

How to check your own content

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

Read the write’s report, then diff. set_page_body and create_page_from_markdown return a validation array listing what the write cleaned or dropped — a lost line under dropped_content, a stripped attribute group or id under dropped_attributes — and every body tool returns a warning when it stripped an attribute group. To see exactly what was stored, read the page back with get_page_body and compare it to the markdown you supplied; every row in the discard table above shows up in that diff. 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.