Skip to content

Embed Diagrams

David Benson edited this page Oct 7, 2026 · 35 revisions

This page shows how to keep diagrams in GitHub READMEs, Markdown files and wikis so that they display as normal images and stay editable in draw.io. It is for developers documenting a repository; for embedding the editor or the viewer in your own application, see Embedding.

Editable images

draw.io can store the complete diagram inside a PNG or SVG file. The file is an ordinary image that GitHub, browsers and Markdown renderers display, and draw.io opens it as the diagram it came from. By convention such files are named *.drawio.svg or *.drawio.png.

.drawio.svg .drawio.png
Rendering Vector, sharp at any zoom; text and links preserved Bitmap
Where the diagram is stored content attribute of the <svg> element A text chunk with the keyword mxfile (mxGraphModel in older files such as the example below)
Diffs Text, but the diagram is a single attribute Binary
Use for Most documentation Places that do not accept SVG

The image shows the first page of a multi-page diagram; all pages are kept in the embedded copy. When draw.io saves a file whose name ends in .svg or .png, it writes this format, with or without .drawio in the name (EditorUi.prototype.getFileData). The embedding format is described in File format.

To create one from an existing diagram:

  • File > Save as and choose Editable Vector Image (.svg) or Editable Bitmap Image (.png), or
  • File > Export as > SVG (or PNG) with Include a copy of my diagram checked; the suggested file name then ends in .drawio.svg (or .drawio.png).

Reference the file like any image:

![Architecture](docs/architecture.drawio.svg)

Labels with formatted text are drawn with HTML inside the SVG (foreignObject), which browsers display but some other SVG tools do not; see SVG export text problems. Exported SVG images can also use adaptive colours that follow the reader's light or dark mode.

Editing in a repository

With app.diagrams.net. Open app.diagrams.net/?mode=github, authorise draw.io for GitHub, and open the file from your repository. Save commits the change to the branch (you are asked for a commit message). New files can be created the same way; choose a name ending in .drawio.svg or .drawio.png. A link of the form https://app.diagrams.net/#H<owner>%2F<repo>%2F<branch>%2F<path> opens a file directly (see supported location hash properties). GitHub mode uses the GitHub REST API and is described in Storage backends.

With the desktop app. Clone the repository, open the .drawio.svg or .drawio.png file in draw.io Desktop, save, then commit and push as usual. See Desktop app.

With Visual Studio Code. The unofficial Draw.io Integration extension (hediet/vscode-drawio) edits .drawio, .dio, .drawio.svg and .drawio.png files inside VS Code, using the draw.io editor in embed mode. Create an empty file with one of these names to start a new diagram; the Draw.io: Convert To... command converts between the formats. The extension also works in github.dev, the browser-based editor you get by replacing .com with .dev in a repository URL. See Diagram in VS Code and Use github.dev to edit diagrams.

If reviewers should see what changed, keep a plain .drawio file (uncompressed XML diffs line by line) and export the image from it, or use .drawio.svg, whose XML is at least text.

Editing in a wiki

A GitHub wiki is a separate Git repository (https://github.com/<owner>/<repo>.wiki.git) that the GitHub REST API cannot read or write, so the GitHub mode of app.diagrams.net cannot open wiki files. Clone the wiki repository, edit its images with the desktop app or the VS Code extension, then commit and push. Images in a wiki are referenced relative to the wiki root, for example ![Alt](images/someimage.png).

This page does exactly that. Here is an editable vector image:

Database Schema

And the same diagram as an editable bitmap image:

Database Schema

Both files are in the images folder of this wiki. To use them from outside the wiki:

The #U links load the image from its raw URL and read the embedded diagram; the URL must be URI-encoded. The same works for files in any public repository, using https://raw.githubusercontent.com/<owner>/<repo>/<branch>/<path>. Lightbox and URL options are described in Embedding.

More GitHub examples

jgraph/drawio-github has further examples: an edit-diagram.html page that edits diagrams in a repository through the GitHub API, self-editing SVG and HTML files, and SVG diagrams that switch between light and dark mode with CSS. The user documentation for GitHub is at draw.io and GitHub.

See also

Clone this wiki locally