draw.io
Embed and render interactive draw.io diagrams with zoom and pan.
The drawio shortcode embeds a draw.io diagram directly in the page. Readers can zoom, pan and navigate layers without leaving the documentation. The draw.io viewer script loads only on pages that contain at least one diagram.
File location
Where you place the .drawio file determines how it is loaded.
| Path style | Where the file lives | How it is loaded |
|---|---|---|
diagram.drawio (no leading /) |
Next to the page’s index.md as a page bundle resource |
Read at build time, embedded inline, works on private sites |
/path/to/diagram.drawio (leading /) |
In assets/ at that path |
Read at build time, embedded inline, works on private sites |
| Fallback (file not found in bundle or assets) | In static/ at that path |
Fetched at runtime, public sites only |
Page bundle resources sit in the same directory as the page’s index.md. For a page at content/docs/en/guides/setup/index.md, a file at content/docs/en/guides/setup/diagram.drawio is referenced simply as diagram.drawio.
Build-time embedding means the diagram XML is written directly into the HTML. No HTTP request is made when the reader opens the page, so the embed works even on private GitLab Pages or any other auth-gated host.
Usage
{{< drawio "diagram.drawio" >}}Or with an absolute path from assets/:
{{< drawio "/docs/files/architecture.drawio" >}}Live example
The demo file lives at exampleSite/assets/docs/files/example.drawio in the theme repository and is embedded inline at build time.
{{< drawio "/docs/files/example.drawio" >}}Use the toolbar to zoom in, zoom out, and fit the diagram to the container. You can also pan by clicking and dragging.
Parameters
| Parameter | Description |
|---|---|
| 1st positional | Path to the .drawio file. Relative paths resolve as page bundle resources. Absolute paths (leading /) resolve from assets/. |
Notes
- The viewer script (
drawio-viewer-static.min.js) is bundled with the theme and works fully offline. - Diagrams load after page JavaScript runs, so a brief loading state is normal.
- The viewer is read-only. To edit diagrams, use the draw.io desktop app or diagrams.net.
- Interactive embeds are replaced with a static note in the printable handbook.