Plan: verify content blocks work across RichText (Tiptap) and Markdown editors

[BahaaKhateeb123]

Verbatim from batch: "a plan for the blocks to work on rich text and tiptap (same blocks — we need to check if we have this)".

Goal (to confirm): audit the content blocks (faq / alert / keyTakeaways / summary / intro / prosCons) and verify each is available, renders, and round-trips in both the RichText (RichTextField / Tiptap) editor and the Markdown editor — same block set in both. Produce a plan for any gaps.

⚠️ Needs scoping — confirm intended scope (RichText vs Markdown parity? edit + read modes? which blocks?).

From bug-board batch.

[suleimansh]

Audit: content-block parity across the RichText (Tiptap) and Markdown editors

Scope confirmed: full parity target (insert + round-trip) for all six default content blocks: faq, alert, keyTakeaways, summary, intro, prosCons.

Current state

Surface	RichText (TiptapEditor)	Markdown (MarkdownEditor)	Read-side (render.ts)
Nodes registered	all 6 (...contentBlockNodes)	Alert only	n/a
Slash insert	all 6 ("Content" group)	none (no slash menu wired)	n/a
Markdown round-trip	n/a	Alert only (:::alert{...})	n/a
Edit-in-place NodeView	all 6	Alert only	n/a
HTML output	n/a	n/a	all 6

Answer to "do we have this?": No. Only Alert has Markdown-editor parity. The other five blocks are absent from the Markdown editor entirely (no node, no markdown storage spec, no insert path). The read-side renderer already covers all six, so this is purely an authoring/round-trip gap in the Markdown editor. Tests cover Alert's round-trip only.

Reference points:

• Markdown editor extension list: src/react/MarkdownEditor.tsx (imports Alert/AlertTitle/AlertBody only; no SlashCommandExtension).
• Alert's round-trip pattern to mirror: Alert.addStorage().markdown + serializeAlertMarkdown + setupAlertDirective in src/extensions/contentBlocks.ts.
• Read-side parity (already complete): src/render.ts:190-200.

Plan to full parity

Each node only needs a markdown storage spec (a markdown-it container directive :::name{attrs} + a serializer); these specs are inert when the Markdown extension is absent, so they are safe to add to the shared node defs without affecting the RichText editor.

• Phase 1 - Generic directive engine + simple labelled blocks (intro, summary, keyTakeaways).
  Generalize the per-Alert setup...Directive into a reusable :::block-name{attrs} parse/serialize helper, then extend the labeledBlock() factory to opt into it. summary carries variant (default/article). Register the three nodes in MarkdownEditor. Tests.

• Phase 2 - prosCons. :::pros-cons wrapping two sub-sections (design the inner split, e.g. nested :::pros / :::cons). Register ProsCons/ProsColumn/ConsColumn. Tests.

• Phase 3 - faq. Most complex (nested faq > faqItem > question + answer, plus the open accordion attr). Design a :::faq serialization for repeated Q/A. Register the faq node family. Tests.

• Phase 4 - Insertion UX (slash menu in Markdown editor). The Markdown editor has no slash menu, so even Alert is only insertable by typing :::alert in source. Factor the slash wiring out of TiptapEditor (SlashCommandExtension + SlashMenu + document-level key handling) into a shared hook and mount it in MarkdownEditor, exposing the same "Content" group. This is what makes the six blocks insertable (the "full parity" half).

• Phase 5 - Anti-drift contract test. A shared test asserting the same block set is registered and round-trips in both editors, so they never diverge again.

Open design decisions (resolve in Phase 1)

1. Directive naming: :::key-takeaways (kebab, matches user-facing) vs :::keyTakeaways (node name).
2. One generic directive engine vs per-block markdown-it rules (recommend generic to avoid N bespoke parsers).
3. FAQ Q/A serialization shape (Phase 3) - nested directives vs heading-based.

Suggested follow-up issues

• Phase 1 (engine + intro/summary/keyTakeaways round-trip)
• Phase 2 (prosCons round-trip)
• Phase 3 (faq round-trip)
• Phase 4 (Markdown-editor slash menu / shared slash wiring)
• Phase 5 (parity contract test)

Phases 1-3 are independent and parallelizable; Phase 4 depends on nothing block-specific; Phase 5 lands last.