feat: document Draw.io source onboarding

README.md

@@ -17,7 +17,8 @@ documentation-docusaurus/
     ├── diataxis-patterns.md          # Template per quadrant, decision tree, cross-linking
     ├── writing-guide.md              # Voice, words to cut, inclusive language, checklist
     ├── config-reference.md           # docusaurus.config.ts — what matters, what to leave alone
-    └── deployment.md                 # Vercel, Netlify, GitHub Pages, Cloudflare, debugging
+    ├── deployment.md                 # Vercel, Netlify, GitHub Pages, Cloudflare, debugging
+    └── drawio-source-diagrams.md     # Editable Draw.io source rendering in Docusaurus MDX
 ```
 
 ## The core idea

SKILL.md

@@ -8,15 +8,18 @@ description: >
   admonitions, editing docusaurus.config.ts, applying voice and inclusive-language standards,
   or setting up deployment to Vercel, Netlify, GitHub Pages, or Cloudflare Pages. Triggers on
   docs/, blog/, docusaurus.config, sidebars.ts, .mdx files, or any request to write, improve,
-  or restructure documentation — even when the user only says "write docs", "document this",
+  render editable Draw.io sources with docusaurus-plugin-drawio, or restructure documentation — even when the user only says "write docs", "document this",
   or "the docs are a mess". Asks who the reader is and what they should be able to DO before
   writing, because the answer decides the structure.
 license: MIT
 metadata:
   author: workspace-skills-code-agent
-  version: "1.0"
+  version: "1.1"
   spec: agentskills.io/specification
   framework: Diátaxis
+  hermes:
+    tags: [docusaurus, documentation, diataxis, drawio, mdx]
+    related_skills: [drawio-main]
 compatibility: Designed for Docusaurus v3. Works with Cline, Claude Code, GitHub Copilot, OpenAI Codex, and other compatible agent environments
 ---
 
@@ -126,6 +129,10 @@ Use these replacements. This isn't optional:
 
 ## Dynamic Documentation Patterns
 
+### Draw.io source diagrams
+
+When a page needs a Draw.io diagram, keep the editable `.drawio` XML in the documentation repository and render that source directly with `docusaurus-plugin-drawio`. Load `drawio-main` to author or change the diagram, then follow [references/drawio-source-diagrams.md](references/drawio-source-diagrams.md) to install the plugin with pnpm, register it, consume the source from MDX with `@theme/Drawio` and `!!raw-loader!`, select multi-page diagrams, and verify the production build and browser rendering. An exported PNG/SVG alone is not an onboarded source diagram.
+
 ### Interactive Elements (Use Sparingly)
 
 Tabs for platform differences:
@@ -173,6 +180,7 @@ Load the one that matches the task. Don't read all four.
 | Write a page, or decide which quadrant it belongs in | [references/diataxis-patterns.md](references/diataxis-patterns.md) — copy-ready template per quadrant, the decision tree, and how to link between them |
 | Write or edit prose, headings, lists, or code examples | [references/writing-guide.md](references/writing-guide.md) — voice, words to cut, inclusive language, pre-publish checklist |
 | Touch `docusaurus.config.ts` | [references/config-reference.md](references/config-reference.md) — the options that matter, sensible defaults, config anti-patterns |
+| Onboard or render an editable `.drawio` source | [references/drawio-source-diagrams.md](references/drawio-source-diagrams.md) — pnpm install, plugin registration, MDX raw-source import, viewer options, and verification |
 | Ship the site, or debug a failing build | [references/deployment.md](references/deployment.md) — Vercel, Netlify, GitHub Pages, Cloudflare, and common failures |
 
 ## Getting Started

references/drawio-source-diagrams.md

@@ -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.