Plugins Diagrams

show code pictures, video and diagrams @mdsvex/plugin-diagram@0.1.1

Diagrams

Diagrams: mermaid fences drawn at build time by pele, or in the browser by mermaid

Install

pnpm add -D @mdsvex/plugin-diagram pele

It needs one of pele or mermaid, its optional peers. For mermaid instead:

pnpm add -D @mdsvex/plugin-diagram mermaid

Turn it on

import { diagram } from '@mdsvex/plugin-diagram';

mdsvex({ plugins: [diagram()] });

What it reads

```mermaid

owns diagram · claims mermaid fences

An example

You write
```mermaid
graph LR
  source --> parser --> plugins --> component
```

You get
sourceparserpluginscomponent
Diagram source
graph LR
  source --> parser --> plugins --> component
Build-time preview. It can’t run in the browser yet: engine.js imports node:module when the plugin loads, to find which engine is installed.

Each mermaid fence is drawn as a diagram, by pele or by mermaid. Both are optional peer dependencies, install the one you want. engine: 'auto', the default, takes pele when it is installed and mermaid otherwise, and the choice is made once, when diagram() runs, so the page never imports a package you didn't install. With neither installed it throws a DiagramError that says what to install.

With pele the diagram is drawn at build time and the page ships the SVG, with no script, so it shows without JavaScript too. It is themed by CSS variables such as --pele-bg and --pele-fg, with dark values for a reader whose system is dark, so light and dark need no second render. A diagram pele can't draw is a diagram_error warning at its fence and shows its source, and diagram({ strict: true }) fails the build there instead. pele passes render options such as fontFamily. pele reads Mermaid syntax with its own layout, and has no Mermaid themes, no HTML labels and no JavaScript click callbacks.

With mermaid the server renders the code and the browser loads mermaid on a page that has a diagram and draws it in place of the code. Without JavaScript the reader sees the code.

The plugin wraps each mermaid fence in a diagram directive, so the code still renders through whatever replaces pre, as the source in a closed "Diagram source" disclosure under the drawing. The title and caption of the fence go around the diagram, and accTitle: and accDescr: name it for screen readers. The plugin claims the mermaid language, so the highlighter never sees these fences, the code renders plain and nothing warns.

Options, from its types 5

engine?: DiagramEngine
Auto, the default, draws with pele when it is installed and with mermaid otherwise, pele draws at build time and mermaid in the browser
css?: boolean
False leaves the default stylesheet out, the markup and its class names stay the same
theme?: string
Mermaid only, the theme of every diagram, by default dark for a reader whose system is dark and default otherwise
pele?: Record<string, unknown>
Pele only, the render options of every diagram, such as fontFamily or links, the plugin sets idPrefix for each
strict?: boolean
Pele only, true fails the build at a diagram pele can not draw, by default that is a warning and the diagram shows its source

Components @mdsvex/plugin-diagram/PeleDiagram.svelte, @mdsvex/plugin-diagram/MermaidDiagram.svelte

Stylesheet @mdsvex/plugin-diagram/diagram.css, or diagram({ css: false }) for none

Find another plugin · Write your own

mdsvex, markdown with Svelte in it. MIT licence.