Drawio

draw.io Diagram Generator

Quick Start: Author the diagram as mxGraph XML → wrap in <div class="mxgraph" data-mxgraph='{"xml":"…"}'> → include the viewer script tag once per page → diagrams auto-render in any browser.

When to use this skill vs. others

draw.io's strength is the shape catalog and the round-trip: anyone who clicks the diagram in the lightbox can copy the XML straight into app.diagrams.net and edit it.

Critical Rules

Rule 1: One viewer script per page

Include this once per HTML page or rendered Markdown document — not per diagram:

<script src="https://viewer.diagrams.net/js/viewer-static.min.js"></script>

For offline/air-gapped use, self-host viewer-static.min.js (~400 KB).

Rule 2: Diagram = single <div> with JSON config

Every diagram is one <div class="mxgraph"> with the XML packed into a data-mxgraph JSON attribute. Do not wrap the div in a code fence.

<div class="mxgraph" style="max-width:100%;border:1px solid #ccc;"
     data-mxgraph='{"highlight":"#0000ff","nav":true,"toolbar":"zoom layers","edit":"_blank","xml":"<mxfile>…</mxfile>"}'></div>

Rule 3: Escape the XML for JSON

The xml value is a JSON string, so " becomes \", newlines become \n. The simplest workflow: keep the XML in a .drawio file during authoring, then minify + JSON-escape when embedding. See examples/ for the pattern.

Rule 4: mxGraph XML skeleton

Every diagram has the same outer shell. You only edit the <root> contents.

<mxfile host="app.diagrams.net">
  <diagram id="d1" name="Page-1">
    <mxGraphModel dx="1200" dy="800" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="1169" pageHeight="826" math="0" shadow="0">
      <root>
        <mxCell id="0"/>
        <mxCell id="1" parent="0"/>
        <!-- your shapes & edges here -->
      </root>
    </mxGraphModel>
  </diagram>
</mxfile>

Rule 5: Cells are vertices or edges

• Vertex (shape): <mxCell id="v1" value="Web Server" style="…" vertex="1" parent="1"><mxGeometry x="40" y="40" width="120" height="60" as="geometry"/></mxCell>
• Edge (connector): <mxCell id="e1" style="endArrow=classic;" edge="1" parent="1" source="v1" target="v2"><mxGeometry relative="1" as="geometry"/></mxCell>

parent="1" puts the cell on the default page layer. id values must be unique within the diagram.

Rule 6: Style strings drive appearance

Style is a semicolon-separated list of key=value pairs. The most useful ones:

Open app.diagrams.net, draw a shape you want, right-click → Edit Style — that gives you the exact style string to copy.

Rule 7: Use shape libraries instead of redrawing

draw.io ships with these libraries — call them by their mxgraph.<lib>.<shape> style names rather than building rectangles by hand:

Viewer config options

Common data-mxgraph keys:

Examples

Best Practices

1. Author in the editor, embed the export. Build the diagram visually at app.diagrams.net, then Extras → Edit Diagram to copy the XML. Hand-writing mxGraph XML for anything beyond 10 cells is unproductive.
2. Keep .drawio source alongside .md. The XML embedded in HTML is hard to diff. Commit the original .drawio next to the Markdown.
3. Don't escape twice. When pasting XML into data-mxgraph='{"xml":"…"}', escape " → \" once. Double-escaping silently breaks rendering.
4. One viewer script per page. Multiple <script> tags work but waste bandwidth.
5. For air-gapped environments, self-host viewer-static.min.js and add <base> or vendor it. Don't rely on the CDN for production docs.
6. For static export (PDF, PNG, slides): use the drawio-desktop CLI — drawio --export --format svg input.drawio — and embed the SVG directly. The viewer script is only needed for interactive viewing.