Repository navigation
Embed Diagrams
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.
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:
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.
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.
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 .
This page does exactly that. Here is an editable vector image:
And the same diagram as an editable bitmap image:

Both files are in the images folder of this wiki. To use them from outside the wiki:
- View the image: https://raw.githubusercontent.com/wiki/jgraph/drawio/images/schema.png
- View the diagram in the lightbox: https://app.diagrams.net/?lightbox=1#Uhttps%3A%2F%2Fraw.githubusercontent.com%2Fwiki%2Fjgraph%2Fdrawio%2Fimages%2Fschema.png
- Use the diagram as a template for a new diagram: https://app.diagrams.net/#Uhttps%3A%2F%2Fraw.githubusercontent.com%2Fwiki%2Fjgraph%2Fdrawio%2Fimages%2Fschema.png
- Edit a diagram in a normal repository with GitHub mode (sign-in required, saving needs write access): https://app.diagrams.net/#Hjgraph%2Fdrawio-diagrams%2Fdev%2Fdiagrams%2Fschema.xml
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.
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.
Describes the dev branch of jgraph/drawio as of release 32.3.0 (October 2026). Internal JavaScript APIs change between releases; check the code of the version you use. · Questions: Discussions · Bugs: Issues · Vulnerabilities: report privately · User docs: drawio.com/docs
Get started
Concepts
Guides
- Self-hosting
- Configuration
- Storage backends
- OneDrive app registration
- Embedding
- Diagrams in GitHub
- Plugins
- Extending the editor
- Shapes and stencils
- Import and export
- Desktop app
- Internationalization
Reference
Project
Elsewhere