@stesura/mermaid

Framework-free Mermaid diagrams: the node spec, commands, rendering, markdown and DOCX support. The editor UI is in @stesura/mermaid-react. See the diagrams guide for setup and behaviour.

Mermaid itself is only import()ed by the render functions, and mermaid and dompurify are optional peers (installed with @stesura/mermaid-react). A server imports the node spec from @stesura/mermaid and needs neither.

Schema

mermaidNodes / mermaidNodeSpec

The mermaid node: a block atom whose text content is the source (content: "text*"), with measureAs: "atomic" for pagination. toDOM writes the source in a pre; parseDOM also reads a GitHub-style pre > code.language-mermaid.

import { stesuraSchema } from '@stesura/core/schema'
import { mermaidGlobalAttributes, mermaidNodes } from '@stesura/mermaid'
 
const schema = stesuraSchema({
  nodes: mermaidNodes,
  globalAttributes: { nodes: mermaidGlobalAttributes },
})

mermaidGlobalAttributes

The globalAttributes.nodes delta granting the node spacing, spanColumns and trackChanges.

mermaidSource / isMermaidNode / MERMAID_NODE_NAME

mermaidSource(node) is the current source: the text without tracked deletions. isMermaidNode narrows a node; MERMAID_NODE_NAME is "mermaid".

MERMAID_THEMES

export const MERMAID_THEMES = ["default", "neutral", "dark", "forest", "base"] as const;

Mermaid’s built-in themes; default renders with no theme directive.

MermaidTheme

export type MermaidTheme = (typeof MERMAID_THEMES)[number];

One of MERMAID_THEMES.

Commands

insertMermaid

setMermaidSource

DEFAULT_MERMAID_SOURCE is the starter flowchart insertMermaid uses when given no source.

setMermaidTheme

deleteMermaid

selectedMermaidPos

Rendering

Browser only. Every caller (the node view, its preview, the DOCX export) goes through these, so the security limits hold everywhere. See Diagrams → Security.

renderMermaidSvg

Renders a source to a sanitized SVG string. Rejects with a MermaidRenderError whose reason is "too-large" (over MERMAID_SOURCE_MAX), "timeout" (over MERMAID_RENDER_TIMEOUT_MS) or "invalid"; for "invalid", detail holds Mermaid’s own message (English, quotes the input: log it, don’t show it).

MermaidRenderErrorReason

export type MermaidRenderErrorReason = "too-large" | "timeout" | "invalid";

Why renderMermaidSvg rejected: over MERMAID_SOURCE_MAX, over MERMAID_RENDER_TIMEOUT_MS, or Mermaid’s own parse error.

rasterizeSvg

Draws an SVG string to a PNG through a canvas, at scale× its viewBox size. Returns the PNG bytes and the CSS-px size to display it at.

loadMermaid

The cached import() of Mermaid and DOMPurify, initialized with the locked-down config. A failed load is retried on the next call.

Markdown

mermaidMarkdown

A MarkdownExtension mapping the node to a mermaid fence, both ways. Spread it into parseMarkdown / serializeBlocks options, or register it for a schema with registerMarkdownExtensions from @stesura/markdown.

DOCX

mermaidDocx

DocxExportOptions plus a nodeTransform for import:

import { downloadDocx, importDocx } from '@stesura/docx'
import { mermaidDocx } from '@stesura/mermaid'
 
await downloadDocx(state, comments, 'report.docx', mermaidDocx)
await importDocx(file, schema, { nodeTransform: mermaidDocx.nodeTransform })

MERMAID_DESCRIPTION_PREFIX is "mermaid:".