ARTICLE AD BOX
I’m planning to add custom block components to Tiptap—specifically callouts (info, success, warning, tip), and later cards and accordions. Since Markdown doesn’t natively support these kinds of blocks, I’m looking for guidance on the cleanest long-term approach.
Overview of what I’m trying to do
Use Tiptap to author content with callouts and other custom block components
Persist the content as Markdown (for portability and static rendering)
Render the same Markdown consistently on hosted/static sites
Current idea (high level)
At a conceptual level, I’m considering representing callouts in Markdown using a custom, HTML-like wrapper, while keeping the inner content as standard Markdown.
For example:
Markdown content inside *italic* and **bold**
On the rendering side, this would be transformed into a styled HTML block (e.g. a with classes), while ensuring the inner Markdown remains untouched and renders normally.
Where I’m stuck
I see a few possible approaches, but I’m unsure which one is considered best practice or most future-proof:
Regex-based preprocessing Simple to implement, but feels fragile for nested blocks and long-term maintenance.
AST / parser-level extensions More robust and structured, but significantly more complex to implement.
I’ve experimented with both regex-style transforms and AST-style parsing, but I’m not fully confident I’m heading in the right direction—especially when thinking about scalability, nesting, and maintainability.
What I’m looking for
Guidance on best practices for handling custom blocks like callouts in a Markdown-first setup with Tiptap
Whether storing HTML/JSX-like tags inside Markdown is an acceptable pattern, or if there’s a better alternative
Any recommended patterns or approaches that are used successfully in production (docs sites, blogs, knowledge bases, etc.)
