# 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`](https://github.com/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 `drawio-main` skill to author and validate diagram content.
- Use this `documentation-docusaurus` skill to onboard and render the source in Docusaurus.

Recommended layout:

```text
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:

```bash
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`:

```ts
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:

```text
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:

```ts
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:

```mdx
---
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:

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

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

```mdx
<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:

```bash
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.