drawio mdbook extention

mdBook + draw.io: viewing extension and a clean GitHub team workflow mdBook Renderers

Answer Use the official draw.io viewer inside mdBook and store diagrams as .drawio.svg so they render as normal SVGs yet remain fully editable. For team edits, use github.dev or Codespaces with the Draw.io VS Code extension, or the diagrams.net GitHub integration for direct browser editing. Draw.io Embed HTML options VS Code Draw.io extension Edit diagrams on github.dev Draw.io GitHub integration Draw.io SVG XML

A. Viewing in mdBook (production-ready)

1. Bundle the viewer once: place viewer-static.min.js under theme/drawio/. Draw.io viewer static docs mdBook Theme
2. Enable it in book.toml:

[output.html]
additional-js = ["drawio/viewer-static.min.js"]

3. Embed diagrams in chapters with the viewer container. Put diagram files in src/assets/diagrams/:

<div class="mxgraph" style="max-width:100%;border:1px solid #ddd"
     data-mxgraph='{
       "url": "/assets/diagrams/arch.drawio",
       "toolbar": "zoom layers lightbox",
       "lightbox": "open",
       "fit": true,
       "zoom": 1
     }'></div>

Notes: data-mxgraph accepts either url or inline xml. Toolbar flags control zoom/layers; lightbox gives a full-screen view. Keep files same-origin with the book to avoid cross-origin fetch issues. Draw.io Embed HTML options

B. Alternative: drop-in SVG with embedded source Export or save as .drawio.svg. mdBook will display it like any other image, and editors can reopen it with the embedded XML intact. Example:

![Architecture](../assets/diagrams/arch.drawio.svg)

Tradeoffs: no toolbar or layers without the viewer, but zero JS and excellent portability. Draw.io SVG XML

C. Team editing on GitHub (three good paths)

1. github.dev or Codespaces + VS Code extension

• Open your repo, press . for github.dev (or use Codespaces).
• Install the Draw.io extension, then open any .drawio.svg or .drawio.png to edit in place. Commit via PR. Edit diagrams on github.dev VS Code Draw.io extension

2. Diagrams.net GitHub integration (OAuth)

• Use the official integration to open and save diagrams in your repo via the browser. Useful when teammates do not use VS Code. Draw.io GitHub integration Embed in GitHub markdown

3. Keep .drawio XML files but render via viewer

• Store raw .drawio alongside your book, embed with the viewer as in A. Consider Git LFS if files grow. Draw.io Embed HTML options Racklet mdBook + LFS

D. Repo hygiene and PR-friendly diffs

• Prefer .drawio.svg so reviewers see a rendered diff preview, while still allowing edits.
• For interactive viewer embeds, keep a matching .drawio.svg next to .drawio to make PRs readable, then point the viewer at .drawio.
• Put diagrams under src/assets/diagrams/ and reference them with stable relative paths. Draw.io SVG XML

E. Minimal working example (all in)

book.toml

[book]
title = "Docs with Draw.io"

[output.html]
additional-js = ["drawio/viewer-static.min.js"]  # bundled under theme/drawio/

<!-- In a chapter .md (raw HTML passthrough) -->
<div class="mxgraph" data-mxgraph='{"url": "/assets/diagrams/arch.drawio","toolbar":"zoom layers"}'
     style="max-width:100%;height:520px;border:1px solid #ddd"></div>

<p>Static fallback:</p>
<img alt="Architecture" src="/assets/diagrams/arch.drawio.svg" style="max-width:100%">

F. Decision guide

• Want interactivity (layers, zoom) inside mdBook: use the viewer container. Draw.io Embed HTML options
• Want the simplest path with great PR diffs: commit .drawio.svg and use an <img>. Draw.io SVG XML
• Want lightweight edits in the browser: github.dev + VS Code extension. Edit diagrams on github.dev

G. Notes on hosting the viewer Use the self-hosted viewer-static.min.js to avoid third-party script fetches. If you must load from the CDN, add a raw HTML <script src="https://viewer.diagrams.net/js/viewer-static.min.js"></script> in a chapter or theme template. Draw.io viewer static docs mdBook Theme