feat: document Draw.io source onboarding
This commit is contained in:
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
Reference in New Issue
Block a user