From fe854e431d56488349e65540371a8a2f93aff452 Mon Sep 17 00:00:00 2001 From: jarvis-at-skic Date: Thu, 13 Aug 2026 17:48:09 +0000 Subject: [PATCH] feat: document Draw.io source onboarding --- README.md | 3 +- SKILL.md | 12 ++- references/drawio-source-diagrams.md | 146 +++++++++++++++++++++++++++ 3 files changed, 158 insertions(+), 3 deletions(-) create mode 100644 references/drawio-source-diagrams.md diff --git a/README.md b/README.md index d526a99..60a1930 100644 --- a/README.md +++ b/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 diff --git a/SKILL.md b/SKILL.md index e6023d0..5676b37 100644 --- a/SKILL.md +++ b/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 diff --git a/references/drawio-source-diagrams.md b/references/drawio-source-diagrams.md new file mode 100644 index 0000000..24cbe3a --- /dev/null +++ b/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'; + + +``` + +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 + +``` + +Or select a stable page ID when the source uses one: + +```mdx + +``` + +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.