Repository navigation
Description
Description
Since #36002 (PR #36253), the workflow fire endpoints convert a Block Editor field supplied as Markdown into Tiptap/ProseMirror JSON server-side. But Markdown has no syntax for the rich nodes the editor persists (dotContent embedded contentlets, dotVideo, youtube, gridBlock, aiContent, or customer-supplied custom blocks), so today:
- A Markdown write to a document containing rich blocks is ignored (existing document kept, warning logged). The save returns 200 and the caller has no signal that nothing was applied.
- The overwrite guard's whitelist is missing
youtubeandimage, so a single YouTube embed wrongly blocks all Markdown writes to that document. - Constructs the guard does not inspect are lost silently: merged table cells (
colspan/rowspan/colwidth), text alignment, underline/sub/sup, linktarget/rel. - The JSON-to-Markdown direction flattens rich nodes to plain text (
dotContentemits its title), so aJSON -> MD -> JSONround trip destroys them.
This blocks non-interactive clients (AI agents via MCP, headless imports) from updating any content that contains an embed, which is exactly the content Markdown-driven agents are expected to maintain.
What we want
Give every rich node a Markdown form so the round trip is lossless, using fenced code blocks with dotcms-* info strings. This is standard CommonMark, preserved verbatim by every parser and by LLMs, and parseable with the fence handling TiptapMarkdown already has:
```dotcms-content
{"identifier": "2d5d1c4c-...", "languageId": 1, "title": "Q3 Report"}
```
- Thin payloads:
dotContent/dotImage/dotVideoneed onlyidentifier(pluslanguageId); the server already rehydratesattrs.datafrom the identifier on every read (StoryBlockAPI.allowedTypes).titleis emitted for readability and ignored on parse.gridBlockcarries its node subtree verbatim (children preserved, not Markdown-editable). Unknown/custom node types (remotecustomBlocksextensions) are carried by a genericdotcms-nodefence with the raw node JSON. - Parsing is always on: any inbound Markdown may contain these fences. Payloads are untrusted: strict per-label schema, hard-coded node type per label (no type smuggling), size caps. Any invalid fence degrades to an ordinary
codeBlockand never throws (consistent with feat(tiptap): convert Story Block content to Markdown (#35727) #35728's graceful-degradation contract). - Emission is opt-in:
toMarkdown()output stays byte-identical, since dotAI embeddings (dotAI: embed Block Editor (Story Block) fields as Markdown instead of HTML-stripped text #36003) and$storyBlock.toMdtemplate output must not change. A new round-trip mode emits the fences, exposed via$markdownTool/StoryBlockMapoverloads. - The guard becomes honest and shrinks: whitelist
youtube/image(bugfix); each fence added removes its type from the "unrepresentable" set; when a write still cannot be applied or would degrade content (e.g. merged table cells), say so in the existing response envelope (ResponseEntityView.messages). This is additive with no contract change: the endpoint keeps accepting writes exactly as today. - Marks/alignment (
textAlign, underline, linktarget) carried via block-level<!-- dotcms:attrs {...} -->comment decorations (block comments already survive the parser today). - Update the MCP server guidance (
execute.ts) that still describes pre-Workflow fire: convert Block Editor Markdown to ProseMirror JSON on save (server-side) #36002 behavior.
Related work
- Convert Tiptap Story Block content to Markdown #35727 / PR feat(tiptap): convert Story Block content to Markdown (#35727) #35728: TiptapMarkdown converter (the fence parse/emit machinery is already there)
- Workflow fire: convert Block Editor Markdown to ProseMirror JSON on save (server-side) #36002 / PR 36002 workflow fire convert block editor markdown to prosemirror json on save server side #36253: Markdown-on-save seam, detection ladder, overwrite guard
- Workflow fire: convert Block Editor HTML to ProseMirror JSON on save (server-side) #36470 / PR convert Block Editor HTML to ProseMirror JSON on save (server-side) #36473: HTML leg (kept at Markdown parity; HTML vocabulary parity is a separate follow-up issue)
Acceptance Criteria
- Firing with Markdown containing each
dotcms-*fence (dotcms-content,dotcms-image,dotcms-video,dotcms-youtube,dotcms-grid,dotcms-ai,dotcms-node) stores a valid Tiptap document; embedded contentlets read back fully hydrated via GraphQL/REST with no human re-save. -
JSON -> toMarkdown(round-trip mode) -> toTiptapis a fixed point for documents composed of all supported node types (asset-bound nodes compared by identifier). - Default
toMarkdown()output is byte-identical to current behavior for the existing test corpus (no dotAI embedding or template regression). - Invalid, oversized, or type-smuggling fence payloads degrade to a plain code block; conversion never throws.
- A document containing only supported rich nodes accepts Markdown writes; when a write is still ignored or degrades content, the fire response carries a message saying what and why (response envelope only; no new rejections, no status-code changes).
- Documents containing a
youtubeorimagenode accept Markdown writes (whitelist fix). - Merged table cells and mark/alignment decorations survive the round trip (or, at minimum for cells, are detected and reported rather than silently lost).
- Server-converted JSON opens and re-saves unchanged in the Block Editor (golden test).
- Security matrix covered by tests: payload schema validation, node-type allow-list, payload size caps, fence content containing backticks or
-->.
Metadata
Metadata
Assignees
Type
Projects
- StatusShow more project fieldsDone
Activity
test(block-editor): pin READABLE Markdown emission byte-parity snapshots
feat(block-editor): dotcms-* fence vocabulary for lossless Markdown r…
feat(block-editor): apply Markdown writes to rich Story Blocks with r…
feat(block-editor): expose ROUNDTRIP flavor to templates and update M…
github-actions commentedon Jul 23, 2026
PRs linked to this issue
fix(block-editor): count a rich node subtree once in replacement warn…
docs(block-editor): document dotcms-* fence vocabulary for API and MC…
docs(block-editor): address review feedback on fence vocabulary
docs(block-editor): address review feedback on fence vocabulary
refactor(block-editor): share the dotcms-* payload validators across …
feat(block-editor): accept the dotcms-* rich-node vocabulary on HTML …
feat(block-editor): accept the dotcms-* rich-node vocabulary on HTML …
refactor(block-editor): share the dotcms-* payload validators across …
feat(block-editor): accept the dotcms-* rich-node vocabulary on HTML …
fmontes commentedon Sep 13, 2026
Documentation impact — 4 pages on dev.dotcms.com need updating
The
dotcms-*vocabulary from this issue (plus the Markdown/HTML save path from #36002 and the HTML leg in #36659) isn't documented anywhere public. The feature targets AI agents and headless clients — exactly the users who can only discover a capability if it's written down. Today the only way to learn the vocabulary is to readTiptapMarkdown.java.Pages
dotcms-*fences,<dotcms-*>elements,<!-- dotcms:attrs -->, or the overwrite behavior changeparse/parseFile—blockToMarkdownis missing entirely, both formsaiContent,gridBlockand custom/remote blocks — the three that now have a Markdown form. Block Types table also lacks system names fordotContentand the AI blockmessagesTwo things to flag to the writer
The Block Editor page is now wrong, not just incomplete. It frames saving raw HTML as something you get "by leveraging the ability to convert a WYSIWYG field to a Block Editor field." HTML — and Markdown — are accepted on the save path generally, with no relationship to WYSIWYG conversion.
Terminology trap: PR #36709's description says
$markdownTool.blockToMarkdown(...). The viewtool is registered under the keymarkdown, so the working reference is$markdown.blockToMarkdown(json[, "roundtrip"]);$markdownToolrenders as literal text. Don't copy the PR prose. (The same typo is inTiptapMarkdownReadableParityTest.java:13.)What the docs need to answer
Three questions, nothing more: what can I send, what do I get back, what happens when I get it wrong (invalid payload → plain code block, save still returns 200, never throws). Plus the behavior change: a Markdown/HTML write to a document holding embeds now applies as a full replace and names what it replaced in
messages— it previously returned 200 and changed nothing.Where the answers live
TiptapMarkdown.java→DotcmsFences: labels, required fields, size/depth caps, the two output flavorsTiptapHtml.java: same payloads as HTML attributes — note the hyphenated spellings (language-id,mime-type,text-align) differ from the JSON keysMapToContentletPopulator.java: JSON-vs-Markdown-vs-HTML routing and the exact wording of every advisory messageMarkdownTool.java/StoryBlockMap.java: the two read surfaces;toolbox.xml:321confirms the context keyTiptapMarkdownFenceVocabularyTest.java: worked examples of every valid and degrading payloadDecide before drafting
STORY_BLOCK_MARKDOWN_RICH_OVERWRITE_PROTECTbe public? Useful to a team caught out by the change, and a setting nobody should casually enable.identifier-only fence reads back fully hydrated? Non-obvious and reassuring for exactly that audience.fmontes commentedon Sep 13, 2026
Recipe: see the new behaviour working (REST only)
For whoever writes the docs — a happy-path walkthrough against a demo instance, no edge cases. Every command and output below was run end-to-end on a build carrying the fix. Needs
curlandjq; uses the demo site's Blog type, whoseblogContentfield is a Story Block.0. Get a token
1. Pick an existing contentlet to embed
2. Write a blog post as Markdown, embeds included
The two fenced blocks are the new part — a YouTube embed and an embedded contentlet, neither of which plain Markdown can express.
Markdown went in, a real Block Editor document came out:
Open the post in the Block Editor at this point — it renders and re-saves like any hand-authored document.
3. Read it back — the embed is fully populated
We only sent an
identifier. The server fills in the rest on every read, so the embed can never go stale.{ "identifier": "e7ceee89-3cc5-4e35-9795-5927ac88ad89", "title": "10 Surfing spots to checkout in Tahiti", "urlTitle": "10-surfing-spots-to-checkout-in-tahiti", "contentType": "Blog" }4. Read it back as Markdown
roundtrip.mdcomes back as what went in, embeds and all:Drop
"roundtrip"and you get the old human-readable output instead, where the embeds flatten to a link and a title. That output is unchanged from before and is the one to use for reading, not for writing back.5. Edit the prose and write it straight back
This is the whole point of the feature. Edit
roundtrip.mdhowever you like — change a sentence, add a paragraph — then send it back.{"messages":[],"blocks":["heading","paragraph","bulletList","paragraph","youtube","dotContent"]}Prose edited, both embeds intact, nothing to report. Before this change, that write would have been discarded entirely.
6. The new warning — what happens if you don't carry them over
HTTP 200, the write applies, and the response says exactly what it cost:
This is the behaviour change worth documenting most clearly: it is a warning on a successful save, not an error, and it arrives in
messages— which most clients ignore today.Clean up
Notes
<dotcms-youtube src="…">and<dotcms-content identifier="…" language-id="1">elements (TiptapHtml: accept the same rich-node vocabulary on HTML input (parity with the Markdown leg) #36659). Note the hyphenated attribute names.blogContent { json }and the embed comes back populated exactly as in step 3.$dotcontent.find()takes an inode, not an identifier — worth calling out, it's an easy first-try mistake.