Draw.io Diagrams

Draw.io (also known as diagrams.net) is a powerful, full-featured diagramming tool. ArchDoc embeds the Draw.io editor directly in your documents so you can build polished architecture, network, UML, and BPMN diagrams without leaving your browser.

What is Draw.io?

Draw.io provides:

• Rich shape libraries: AWS, Azure, GCP, Kubernetes, networking, UML, BPMN, mockups, and more
• Familiar drag-and-drop editor: Auto-layout, smart connectors, swimlanes, containers
• High-fidelity output: Diagrams round-trip as SVG so they stay crisp at every zoom level
• Embedded in documents: No external file storage — diagrams live inside the document

When to Use Draw.io

Draw.io is the best choice when you need:

• Detailed architecture diagrams with vendor-specific shape libraries (AWS, GCP, Azure, K8s)
• UML class, sequence, or state diagrams with strict notation
• Network topology and infrastructure diagrams
• BPMN process diagrams
• Mockups and wireframes that benefit from a large shape palette

For lighter-weight diagrams, see Excalidraw (hand-drawn style) or Mermaid (text-based).

Creating a Draw.io Diagram

Inserting a Diagram

1. Place your cursor where you want the diagram in Edit mode
2. Click the Draw.io button in the editor toolbar
3. An empty Draw.io block appears in the document
4. Click Edit on the block to open the full Draw.io editor in a fullscreen overlay

Editing in the Fullscreen Editor

The fullscreen editor gives you the complete Draw.io experience:

• Pick from any of the built-in shape libraries
• Use the formatting panel to change colors, line styles, and fonts
• Group, arrange, and align shapes
• Add multiple pages within the same diagram block

When you're done, click Save in the editor. The diagram is exported as SVG and stored with the document.

Updating an Existing Diagram

1. Open the document in Edit mode
2. Click Edit on the Draw.io block
3. Make your changes in the fullscreen editor
4. Click Save to update the embedded SVG

Rendering and Preview

Draw.io diagrams render as inline SVG everywhere they appear:

• Edit mode — interactive block with an Edit button
• Preview / View mode — sanitized SVG preview that scales with the document width
• GitHub sync — committed alongside the Markdown file as a sibling SVG asset (see below)

The SVG preview is sanitized through a strict allowlist (DOMParser-based) before rendering, so untrusted diagram payloads can't smuggle in scripts or external resource references.

GitHub Sync

When a document with Draw.io diagrams is synced to GitHub, ArchDoc:

1. Extracts the SVG from each Draw.io block
2. Commits it as a sibling asset (e.g. docs/adr/<slug>-drawio-1.svg)
3. Replaces the block in the Markdown with a standard ![]() image reference

The Markdown file and every generated SVG are written in a single atomic commit via the GitHub Git Data API, so reviewers always see the diagram and the prose change together. If a diagram has no SVG payload yet, ArchDoc falls back to fenced xml (mxfile) so nothing is lost.

See Syncing Documents for the full GitHub sync workflow.

Tips

Keep Diagrams Focused

Large diagrams are hard to read in the document preview. Break complex systems into multiple smaller Draw.io blocks, each focused on one concern.

Use Shape Libraries Consistently

If your team has a preferred set of vendor libraries (e.g. AWS), enable them in the editor and use them across documents so diagrams feel cohesive.

Prefer SVG-Friendly Styling

Draw.io diagrams are stored and rendered as SVG. Avoid features that don't round-trip well to SVG (such as some advanced gradients) if you need pixel-perfect rendering on GitHub.

Combine with Other Diagram Types

You can mix Draw.io, Excalidraw, and Mermaid blocks in the same document — use whichever tool fits the diagram you need.

Comparison with Other Diagram Types

Troubleshooting

Diagram doesn't appear after saving

Make sure you clicked Save inside the Draw.io editor (not just the document Save). The editor exports the SVG on save; without that step there's no payload to render.

Preview looks blank

The SVG preview is sanitized through a strict allowlist. If you've imported a diagram that uses unusual external references, those may be stripped. Re-saving the diagram from the embedded editor will produce a clean SVG that renders correctly.

Diagram doesn't show on GitHub

Confirm GitHub sync completed successfully — the diagram is committed as a sibling SVG file alongside the Markdown. You can verify by browsing the directory in your repository; you should see *-drawio-*.svg files next to the document.