147 lines
4.9 KiB
Markdown
147 lines
4.9 KiB
Markdown
# 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.
|