Draw.io
.drawio.svg with an embedded editable copy as an ordinary image. Its edit button opens the Draw.io editor.Draw.io uses plain Markdown images. It has no fence or shortcode.
When exporting from Draw.io, select “Include a copy of my diagram”. The SVG or PNG then contains an mxfile copy.
The theme detects this copy and adds an edit button. Use this integration for diagrams that readers can download and change.
Use an ordinary image for diagrams that only need to be viewed.
Shortest form
To show the edit button, first set params.drawio.enable: true and configure
params.drawio.drawio_server as shown under The editor address.
Without this setup, the diagram remains an ordinary image without editing.
Use ordinary image syntax. The filename does not affect detection. .drawio.svg is only a naming convention.
An export with an mxfile copy is wrapped in a .drawio container.
A pencil button appears at the bottom right on hover or keyboard focus. It stays visible on touch devices and in forced-colors mode.
The button opens a full-screen iframe with the site’s configured editor.
When image zoom is enabled, Edit and Zoom are separate sibling buttons. Edit does not open the zoom dialog.
How the copy is detected
The runtime checks whether the file contains mxfile. It does not check the filename.
A hand-drawn SVG with the same block-image syntax and attribute line has no embedded copy, so it gets no edit button.
With a caption
Draw.io images use the ordinary image render hook. All image attributes apply.
Add caption to create a captioned figure. The edit button still appears on the image.
As a numbered figure
Add {#id num=…} to create a numbered figure. xref can reference it, and it appears in the list of figures.
The complete numbering and cross-reference rules are in publishing books.
SVG or PNG
Both SVG and PNG are recognized. A Draw.io PNG can store the editable copy in a text chunk. The runtime uses the same detection test.

Prefer SVG for documentation. It scales without quality loss, contains searchable text accessible to screen readers, and has readable diffs. Use PNG for very complex diagrams or platforms without SVG support. Only PNG supports Hugo image processing; processing an SVG warns and preserves the source.
What the button does
The button performs three actions in this order.
Lay an overlay over the page
In OINK 1.3.0, the runtime opens a full-screen
<dialog class="drawioframe"> containing an iframe.
The editor URL keeps the configured drawio_server query parameters and fragment,
and sets embed=1, ui=atlas, proto=json, saveAndEdit=1, and noSaveBtn=1.
The modal includes a localized Close button and contains keyboard focus. Close
it with that button or a background click. Escape closes it while focus is in
the host dialog; the embedded editor handles its own keys. Closing restores
focus to Edit unless another surface has already taken focus.
Hand the diagram to the editor
When the editor is ready, the runtime sends the image and its mxfile copy to the iframe as a data URL.
This transfer does not use your server.
Save and write back
When you save, the editor exports the original format, SVG or PNG. The browser downloads it with the same filename.
The runtime never writes to the repository. Replace the file in content/ with the download and commit it yourself.
The edit button lets readers download and change a diagram. It does not edit the site online.
The editor address
enable: truewithoutdrawio_serverwarns and disables editing. The theme does not select a public service.- The address must be an HTTP(S) URL or local path. Local paths honor the
baseURLdeployment subpath. Whitespace, control characters, raw backslashes, protocol-relative URLs (//host/), and other schemes warn and disable editing. - If editing must stay within your organization, deploy a self-hosted editor and configure its address.
- The public endpoint
https://embed.diagrams.net/works. With this endpoint, the reader’s diagram is sent to a third-party page.
Both keys are defined in Configuration.
Output
| Output | Shape |
|---|---|
| HTML | A plain <img> or <figure>; once enabled, the runtime wraps an image that carries a copy in <div class="drawio"> and adds the button |
| The image prints as usual; this output loads no Draw.io runtime and creates no edit button | |
| Markdown | Plain Markdown image syntax |
| RSS | A plain <img> with an absolute URL and no button |
All four outputs include the image. Only HTML adds the optional edit button.
Parameter reference
Draw.io has no fence or shortcode parameters. It uses the Images attribute line:
caption, width, height, link, #id, num, command, and options.
Site parameters (hugo.yml):
Limits
- The runtime loads only if rendered page content has
.svgor.pngcandidates. It groups matching images by URL and reads each URL once to findmxfile. - Without “Include a copy of my diagram” on export, the image has no edit button.
- Editing needs the editor and never writes to the repository. Offline, images display normally, but the button has no effect. Saving downloads a file. You must replace and commit the file manually.
- Exported SVG colors are fixed and do not follow the site’s color scheme.
Use
nonefills and neutral gray lines and text so the image is readable in both modes.
Related
- Images — captions, numbering, sizing and zoom in full
- PlantUML — UML diagrams; see its rendering modes and version requirements
- Mermaid — diagrams from text with no server at all
- Configuration — the full definition of
params.drawio.*