# Diagram Metadata in PNG (drawio.png)

**In short:** A .drawio.png file is a normal PNG image that also carries its own draw.io diagram source. You can show it in documentation and reopen it for editing. Plain XML or SVG files suit Git better.

## Explanation

Draw.io is a diagramming tool. It can hide the diagram's XML source inside an image file. It places that XML in the `zTxt` section of the file, a text area that is not part of the picture itself.

Because the source travels with the image, the file keeps everything needed for further editing. Draw.io uses the `.drawio.png` extension for this. The file displays like a normal PNG in browsers and other viewers, so it is easy to transfer and embed.

**How to create one**

When you export to PNG, keep the option *Include a copy of my diagram* enabled. Without it, you cannot reopen the file for editing in draw.io. Editable SVG exports need the same checkbox.

**How to edit one**

The Draw.io Integration extension for VS Code can edit and save `.drawio.png` and `.drawio.svg` files directly. A Microsoft engineering playbook recommends `.drawio.png` for this reason. It stores source and rendered image together, and VS Code edits it easily.

**Things to watch**

Some image hosts resample PNGs. That can strip the embedded data and leave a plain picture.

**Alternatives**

- Plain `.drawio` files are XML. They diff cleanly in Git.
- `.drawio.svg` files are valid SVGs. You can embed them in GitHub READMEs.

**Automation**

A MkDocs plugin exported draw.io diagrams while building documentation. This shows that export can be automated. The repository is now archived.

## Example

A team keeps its context diagram as `context.drawio.png` in the docs folder. The README shows it as a normal image. When the system changes, an engineer opens the same file in VS Code, edits the boxes, and saves. No separate export step is needed. The team made sure the *Include a copy of my diagram* option was on when they exported.

## Trade-offs

The main benefit is one file that serves as both image and source. The main cost is Git. PNGs are binary, so they do not diff well. The VS Code extension therefore recommends plain `.drawio` files when you want readable diffs for reviewers and AI tools. Image hosts that resample PNGs may also strip the embedded source. Choose `.drawio.png` for convenience, and plain `.drawio` or `.drawio.svg` when review and diffs matter most.



## Checks

- Diagrams meant to stay editable are saved as .drawio.png and were exported with the 'Include a copy of my diagram' option enabled.
- The documentation names an editor that can reopen the embedded diagrams, such as VS Code with the Draw.io Integration extension.
- Where readable Git diffs matter, the team uses plain .drawio files instead of .drawio.png.
- Images that pass through image hosts are checked, because resampling can strip the embedded source.

## Related

- [Documentation as Code](https://arc.fuet.ch/concepts/documentation/documentation-as-code.md)
- [Diagrams as Code](https://arc.fuet.ch/concepts/documentation/diagrams-as-code.md)
- [Modeling Tool vs. Drawing Tool](https://arc.fuet.ch/concepts/modeling-uml/modeling-tool-vs-drawing-tool.md)
- [Kroki](https://arc.fuet.ch/concepts/documentation/kroki.md)
- [Guidelines for Documentation](https://arc.fuet.ch/concepts/documentation/guidelines-for-documentation.md)
- [Self-Documentation](https://arc.fuet.ch/concepts/documentation/self-documentation.md)

## Sources

- [Embedded XML in PNG image files | draw.io](https://www.drawio.com/docs/manual/export/xml-in-png/) — drawio.com, accessed 2026-11-09
- [GitHub - hediet/vscode-drawio: This unofficial extension integrates Draw.io (also known as diagrams.net) into VS Code. · GitHub](https://github.com/hediet/vscode-drawio) — github.com, accessed 2026-11-09
- [Share diagram data in an image file | draw.io](https://www.drawio.com/docs/manual/collaboration/diagram-data-image-formats/) — drawio.com, accessed 2026-11-09
- [Preferred Diagram Tooling - Engineering Fundamentals Playbook](https://microsoft.github.io/code-with-engineering-playbook/design/design-reviews/recipes/preferred-diagram-tooling/) — microsoft.github.io, accessed 2026-11-09
- [GitHub - LukeCarrier/mkdocs-drawio-exporter: Exports your Draw.io diagrams at build time for easier embedding into your documentation · GitHub](https://github.com/lukecarrier/mkdocs-drawio-exporter) — github.com, accessed 2026-11-09