feat: document Draw.io source onboarding

2026-08-13 17:48:09 +00:00
parent fec827c6b7
commit fe854e431d
3 changed files with 158 additions and 3 deletions
@@ -0,0 +1,146 @@
+# 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.