documentation-docusaurus/references/drawio-source-diagrams.md

Draw.io Source Diagrams in Docusaurus

Use this workflow when a Docusaurus v3 site must render an editable Draw.io source file directly. The integration is based on xiguaxigua/docusaurus-plugin-drawio and its upstream README.

Source-of-truth rule

• Commit the editable .drawio XML in the documentation repository.
• Render that source directly in MDX; do not make a PNG/SVG export the only authoritative artifact.
• Keep the source adjacent to, or in a clearly named diagram directory near, the page that consumes it.
• Use the global diagrams-drawio skill to author and validate diagram content.
• Use this documentation-docusaurus skill to onboard and render the source in Docusaurus.

Recommended layout:

docs/
└── architecture/
    ├── context.mdx
    └── diagrams/
        └── system-context.drawio

Install

This platform uses pnpm. Add the plugin and the raw loader required by the upstream import syntax:

pnpm add docusaurus-plugin-drawio
pnpm add -D raw-loader

Commit package.json and pnpm-lock.yaml. Do not substitute npm or create a second lockfile.

Register the plugin

Add the plugin to docusaurus.config.ts or docusaurus.config.js:

export default {
  // ...
  plugins: [
    ['drawio', {}],
  ],
};

Preserve existing plugins. Do not replace the whole array merely to add Draw.io.

The plugin uses this viewer script by default:

https://cdn.jsdelivr.net/npm/docusaurus-plugin-drawio/viewer.min.js

For production environments that require controlled or offline assets, host viewer.min.js from an approved trusted location and configure it explicitly:

plugins: [
  ['drawio', {lib: '/drawio/viewer.min.js'}],
],

Verify the configured path is published and reachable. Do not point production documentation at an unapproved HTTP origin.

Consume a .drawio source file from MDX

The page must use .mdx, because it imports and renders a React component:

---
title: "Architecture context"
description: "System context and external relationships."
---

import Drawio from '@theme/Drawio';
import systemContext from '!!raw-loader!./diagrams/system-context.drawio';

<Drawio
  content={systemContext}
  title="System context"
  toolbar="zoom layers lightbox"
  responsive
/>

The !!raw-loader! prefix loads the Draw.io XML as text. The Drawio theme component passes that XML to the viewer.

For a multi-page source file, select a page by zero-based/numeric page index as supported upstream:

<Drawio content={architecture} page={1} />

Or select a stable page ID when the source uses one:

<Drawio content={architecture} pageId="containers" />

Prefer one source file per durable diagram unless a multi-page source has a clear ownership reason. If using multiple pages, document page names/IDs and verify every consumed page after edits.

Supported display controls

The upstream plugin exposes Draw.io viewer properties including page, pageId, toolbar, zoom, maxHeight, title, responsive, layers, lightbox, and navigation/resize controls. Use only properties verified by the site build and browser rendering. Do not copy undocumented combinations without testing.

Validation

Run the repository's prescribed checks, at minimum:

pnpm install --frozen-lockfile
pnpm build

Then serve or preview the built site and verify in a browser:

1. the page loads without console errors;
2. the diagram is visible and readable;
3. zoom/lightbox controls work when enabled;
4. the selected page/pageId is correct;
5. diagram labels and relationships match the .drawio source;
6. the browser can load viewer.min.js from the configured location;
7. no mixed-content, CSP, missing-module, or raw-loader error appears.

Also verify that every MDX import resolves to an existing committed .drawio file. A successful XML edit without a successful Docusaurus build and browser render is incomplete.

Common failures

• Module not found: raw-loader — add raw-loader as a development dependency and refresh the pnpm lockfile.
• MDX parse/import failure — use .mdx, keep imports after frontmatter, and check the relative source path.
• Blank viewer — inspect browser console/network output, validate the Draw.io XML, and verify viewer.min.js is reachable.
• Wrong page shown — verify page or pageId against the current source; page ordering can drift.
• Works in development but not production — check production base URL, CSP, static asset path, and viewer CDN/network policy.
• Stale exported image — remove the export from the authority path or regenerate it; the .drawio source remains authoritative.

Evidence to record

Record exact paths for:

• .drawio source;
• consuming .mdx page;
• Docusaurus configuration;
• package.json and pnpm-lock.yaml changes;
• build result;
• browser/console verification;
• branch and commit SHA.