docusaurus-plugin-dgmo

Render DGMO diagrams from ```dgmo fenced code blocks in your Docusaurus site at build time. Powered by @diagrammo/dgmo and the framework-agnostic remark-dgmo core. Zero client JavaScript by default.

Every diagram is rendered twice at build time (light + dark palettes) and follows the Docusaurus color-mode toggle via shipped CSS.

Install

pnpm add docusaurus-plugin-dgmo @diagrammo/dgmo

@diagrammo/dgmo is a peer dependency. Node 20.6+. ESM only. Your docusaurus.config.js must be .mjs/.ts/.mts, or your package.json must have "type": "module".

Quick start

Wrap your docusaurus.config.ts with defineConfig. The helper injects the remark plugin into your classic preset's docs/blog/pages slots, sets markdown.format = 'md' (raw-HTML output is incompatible with MDX), and registers docusaurus-plugin-dgmo. Nothing else to wire.

// docusaurus.config.ts
import { defineConfig } from 'docusaurus-plugin-dgmo/config';

export default defineConfig({
  title: 'My Docs',
  url: 'https://example.com',
  baseUrl: '/',
  presets: [
    [
      'classic',
      {
        docs: { sidebarPath: './sidebars.ts' },
        blog: { showReadingTime: true },
      },
    ],
  ],
});

That's the whole integration. defineConfig returns Promise<Config>; Docusaurus accepts a promise as the default config export.

Pass remark-dgmo options as a second argument:

export default defineConfig(
  {
    /* …config… */
  },
  { dgmo: { palette: 'catppuccin', colorMode: 'auto' } }
);

MDX support

By default defineConfig sets markdown.format = 'md' because the rendered diagrams are emitted as raw HTML nodes that MDX rejects. If you want JSX (component imports, frontmatter expressions, etc.) in the same files as your dgmo blocks, opt in:

export default defineConfig(
  {
    /* …config… */
  },
  { mdx: true }
);

This forwards mdx: true to remark-dgmo so it emits an mdxJsxFlowElement (<div dangerouslySetInnerHTML={…} />) which MDX accepts. markdown.format is left alone, so Docusaurus's default 'mdx' parser runs and your files get full MDX features.

Configure (manual)

If defineConfig doesn't fit (custom preset, deeply dynamic config, you need to inspect the wiring), do it by hand:

// docusaurus.config.ts
import type { Config } from '@docusaurus/types';

export default async function createConfig(): Promise<Config> {
  const remarkDgmo = (await import('docusaurus-plugin-dgmo/remark')).default;
  return {
    // …
    markdown: { format: 'md' },
    plugins: ['docusaurus-plugin-dgmo'],
    presets: [
      [
        'classic',
        {
          docs: { remarkPlugins: [remarkDgmo] },
          blog: { remarkPlugins: [remarkDgmo] },
          pages: { remarkPlugins: [remarkDgmo] },
        },
      ],
    ],
  };
}

The async-function default export is required because remark-dgmo is ESM-only and the jiti loader Docusaurus uses to read the config rejects top-level await in a sync default export.

Use

Drop a fenced block with the language dgmo into any .md (or .mdx with mdx: true) file in your docs/, blog/, or pages/ directory.

```dgmo
sequence
Client -POST /login-> API
API -validate-> Auth
Auth -JWT-> API
API -200 OK-> Client
```

Per-block overrides

Append options to the fence info string. Tokens are space-separated; values may be quoted.

```dgmo showcase title="Login flow" palette=catppuccin colorMode=light
sequence
A -> B
```

See the remark-dgmo README for the full option matrix.

Working reference site

tests/fixture/ is a complete minimal Docusaurus 3 site running this plugin. Copy tests/fixture/docusaurus.config.ts as a template for your own site.

git clone https://github.com/diagrammo/docusaurus-plugin-dgmo
cd docusaurus-plugin-dgmo
pnpm install && pnpm build
cd tests/fixture && pnpm install --no-frozen-lockfile && pnpm exec docusaurus start

Opens at http://localhost:3000 with four example diagrams (plain auto, colored tag sequence, showcase mode, per-block override). See tests/fixture/README.md for details.

How CSS is delivered

The plugin's getClientModules() registers two assets:

• remark-dgmo/client.css — three rules that hide the wrong-mode SVG based on [data-theme="dark"] (Docusaurus's color-mode signal on <html>). Docusaurus emits it as a <link rel="stylesheet"> in <head>.
• A small client script (~1.5 KB) that tightens each diagram's viewBox to its content bounds and binds showcase-mode copy buttons. The script is registered as onRouteDidUpdate so it fires on every SPA route change.

Custom color-mode selector

The shipped remark-dgmo/client.css keys on [data-theme="dark"] — the convention Docusaurus uses. For sites with a custom toggle that signals dark mode via .dark or some other selector, see the "Custom color-mode selector" section in the remark-dgmo README.

How it works

1. defineConfig is an async helper that dynamically imports the ESM-only remark-dgmo plugin, then injects it into every docs / blog / pages slot in your classic preset (or any standalone @docusaurus/plugin-content-* entry), sets markdown.format = 'md', and adds 'docusaurus-plugin-dgmo' to plugins[].
2. The plugin itself registers remark-dgmo's CSS and a Docusaurus-shaped client wrapper via getClientModules().
3. At build time, the remark plugin walks the mdast, finds ```dgmo blocks, calls render() from @diagrammo/dgmo once per theme under default colorMode: 'auto', and replaces the block with an html node carrying the rendered wrappers.
4. The client script tightens each SVG's viewBox after every route change.

All rendering happens at build time. The browser ships only the inline SVG + the small CSS rules.

License

MIT