Mermaid#

Mermaid diagrams for sigx — a <Mermaid> component for any app, and drop-in ```mermaid fence support for @sigx/ssg sites.

v0.1.0 ESM-only MIT

Terminal 
pnpm add @sigx/mermaid mermaid

mermaid itself is a peer dependency — you control which version renders your diagrams.

Why it exists#

A docs site without diagrams explains architecture in prose. This package makes fences just work, without giving up the things a static site is for:

  • The diagram source stays in the HTML. It is readable, greppable and indexable, and it survives with JavaScript off.
  • mermaid loads only on pages that have a diagram, and only once one scrolls into view.
  • Diagrams re-theme when the reader flips light/dark, rather than staying committed to the palette they were first drawn in.

In an app#

TSX 
import { Mermaid } from '@sigx/mermaid';

<Mermaid code={`
  sequenceDiagram
    Browser->>Server: GET /
    Server-->>Browser: HTML
`} />

In an SSG site#

@sigx/ssg needs no changes — markdown.shiki.skipLanguages was already the documented seam for exactly this:

TypeScript 
// ssg.config.ts
import { defineSSGConfig } from '@sigx/ssg';
import { rehypeMermaid } from '@sigx/mermaid/ssg';

export default defineSSGConfig({
    markdown: {
        shiki: { skipLanguages: ['mermaid'] },
        rehypePlugins: [rehypeMermaid],
    },
    clientImports: ['@sigx/mermaid/styles', '@sigx/mermaid/client'],
});

Then write a fence:

MDX 
```mermaid title="Request flow"
sequenceDiagram
  Browser->>Server: HTML
```

See SSG integration for the details.

Why not render at build time?#

Rendering to SVG during the build would mean zero client JavaScript, and it is the obvious thing to want.

mermaid cannot do it without a browser: it measures text with getBBox, which neither jsdom nor happy-dom implements faithfully. That leaves a headless Chromium — slow builds and a ~300 MB dependency — or isomorphic-mermaid, which is svgdom-based, young, and approximate on font metrics.

Neither is a good default. So this package renders on the client and keeps the cost honest: the source is always in the HTML, and mermaid is never loaded for a diagram nobody scrolled to.

What's here#