Rebuilding my blog editor: callouts, collapsibles, and diagrams you can control

My blog runs on a custom TipTap editor. For months it covered the basics well — headings, code blocks with syntax highlighting, tables, Mermaid diagrams — but every time I wanted to flag something important, hide a long aside, or let a reader zoom into a dense diagram, I hit a wall. So I rebuilt the editor's block system and fixed the renderer gaps I found along the way. This post is written with the new blocks themselves — what you're reading is the demo.

Callout blocks: say the important thing loudly

Documentation-style callouts — info, tip, warning, danger — are the fastest way to pull a reader's eye to what matters. They didn't exist in my editor, so I built a CalloutExtension as a proper TipTap node with a variant attribute, a React NodeView with a variant picker, and matching renderer styles:

export const CalloutExtension = Node.create({
  name: 'callout',
  group: 'block',
  content: 'block+',
  defining: true,

  addAttributes() {
    return {
      variant: {
        default: 'info', // info | tip | warning | danger
        parseHTML: el => el.getAttribute('data-variant') || 'info',
        renderHTML: attrs => ({ 'data-variant': attrs.variant }),
      },
    }
  },

  addCommands() {
    return {
      insertCallout: variant => ({ commands }) =>
        commands.insertContent({
          type: 'callout',
          attrs: { variant },
          content: [{ type: 'paragraph' }],
        }),
      setCalloutVariant: variant => ({ commands }) =>
        commands.updateAttributes('callout', { variant }),
    }
  },
})

The variant picker lives in the node view header, so I can flip a callout from info to warning without touching the content. Small detail, big authoring win.

Collapsible details blocks: hide the long asides

Some explanations deserve to exist without demanding attention — implementation notes, alternative approaches, the "actually, here's why" paragraphs. The new detailsBlock node renders as a native <details> element. Expand the one below for the design notes on this very block:

Diagrams readers can actually explore

Mermaid diagrams were already supported, but dense ones — sequence diagrams with a dozen participants — rendered at whatever size fit the column, and readers were stuck squinting. The new MermaidViewer ships a floating control toolbar on every diagram:

• Zoom in / out, from 0.5x to 4x

• Drag to pan once zoomed

• One-click reset

• Fullscreen mode (Esc to close)

Try it on this architecture diagram — zoom in and drag around:

The renderer gap nobody noticed

While wiring up the new blocks I audited every node type the editor can produce against every case the renderer handles. The audit caught a real bug: the editor had an internalLink node (for linking between posts and projects), but mdx.tsx had no case for it — so internal links silently vanished from published articles. Authors saw them in the editor; readers never did.

// mdx.tsx — the missing case that swallowed internal links
case 'internalLink': {
  const type = node.attrs?.type === 'project' ? 'project' : 'post'
  const slug = node.attrs?.slug as string
  const title = node.attrs?.title || slug
  const href = type === 'project' ? `/projects/${slug}` : `/blog/${slug}`
  return (
    <Link key={key} href={href} className='...'>
      {title}
    </Link>
  )
}

What's next

If you write with a custom editor, audit your renderer against your node list today. You might find your own vanishing links.