Two New Blocks in the Editor: Mermaid Diagrams and Accordions

Most of what's missing from a documentation editor only shows up once you're actually writing. You don't notice you can't draw a flowchart until you're three paragraphs into explaining one in prose. You don't notice a page has become a wall of text until a reader tells you they gave up halfway down. This week's two additions fix one of each.

Diagrams that are text, not images#

Drop a fenced code block with mermaid as the language, and Dokly renders it as a diagram instead of highlighting it as code:

```mermaid
sequenceDiagram
    participant Agent
    participant Dokly
    participant You
    Agent->>Dokly: update_page(pricing, new copy)
    Dokly->>Dokly: save as a pending revision
    Dokly->>You: review link + diff
    You->>Dokly: Approve
    Dokly->>Dokly: publish
```

renders as:

That's a real diagram, rendered by the same code that renders this post — not a screenshot. Mermaid has been the de facto way to draw a diagram in plain text for years; what's new is that Dokly now understands the language natively, in the editor and on the published page, instead of leaving it as a code block nobody meant to leave unrendered.

A flowchart works the same way:

A few things worth knowing before you reach for it:

• It follows your theme. Light and dark mode both re-render the diagram to match, the same way the rest of the page does — flip the toggle on this post and watch it happen.
• It fails loudly, not silently. Invalid Mermaid syntax shows an error message in place of the diagram rather than a blank box or a raw dump of code. You'll know immediately if a diagram didn't parse.
• It's sandboxed. Diagram source can come from a connected agent writing over MCP, not just a person typing, so rendering runs in Mermaid's strict security mode — no embedded links or scripts execute from inside a diagram.
• It's not an interactive canvas. You write the diagram as text and it renders as a static SVG. There's no drag-and-drop shape editor; if you want that, draw it elsewhere and paste an image instead. The appeal here is that the diagram lives in your docs as text — diffable, searchable, and readable by whatever reads the rest of the page, including an AI agent.

Accordions, for everything a reader can skip#

The second addition is smaller and, for most pages, more useful day to day: a collapsible section.

That whole block is three <Accordion> tags inside one <AccordionGroup>, written directly in this post's MDX. No screenshot — if it looks like it's doing something, click it.

The syntax:

<AccordionGroup>
  <Accordion title="What's included" icon="check">
    Everything in the plan description above, plus email support.
  </Accordion>
  <Accordion title="Advanced configuration" defaultOpen>
    Most teams never need this — it's here for the ones that do.
  </Accordion>
</AccordionGroup>

title is the only required prop. icon takes the same Lucide icon names as Card, description adds a muted second line under the title, and defaultOpen starts that one section expanded instead of collapsed — useful for the one accordion in a group that almost everyone needs to read.

What this doesn't fix#

Dokly still ships fewer MDX components than the larger platforms we're measured against — this closes two gaps in that list, not the list. Mermaid and Accordion were picked in that order deliberately: Mermaid because it needed zero new editor plumbing (a fenced code block already round-trips cleanly through the editor), Accordion because it's a genuinely common pattern with no good existing substitute. The ones still missing — tabs within columns, tooltips, a file tree, inline field references — are the next batches, not a someday list.

If you hit a diagram that won't parse or an accordion that behaves oddly, reply to this post or use the contact page — it reaches me directly.

Changelog entries#

Mermaid diagrams in MDX · Added · Fenced code blocks with the mermaid language now render as flowcharts, sequence diagrams, and other Mermaid diagram types, in the editor and on published pages, matching light/dark mode automatically. Accordion and AccordionGroup components · Added · A new collapsible-section component for optional detail, advanced configuration, or anything a reader should be able to skip — distinct from FAQ, which keeps its question/answer-specific SEO schema.