This explains and demos how to use diagrams.net (draw.io) diagrams in your GitHub repo.
- Diagrams are stored in your repository with your code and docs
- Diagram access is controlled by GitHub repository access
- Diagrams are version-controlled using git
- Create PRs with diagram updates to get approvals and feedback
- One-click diagram editing from your GitHub repository
- diagrams.net is open-source: https://github.com/jgraph/drawio
Note: Images in markdown are cached and can take five minutes to update
This method does not require any OAuth or GitHub app approvals and defaults to offline mode. 🎉
Using the Draw.io Visual Studio Code extension, you can do this in github.dev, Codespaces or locally on VS Code.
- Open the repository you want to create the diagram in
- Press
.
to open github.dev (or use Codespaces, or clone and use VS Code locally) - Install the Draw.io Visual Studio Code extension
- Open or save a file ending with
.drawio.svg
or.drawio.png
(svg is recommended). This will open the draw.io editor in VS Code. - Reference the file using a relative link in markdown like you would reference any file
![Label](relative link)
- It will now live-update, you can use PRs to review changes, and you didn't need to authorize anything! 🚀
Reference: https://github.com/hediet/vscode-drawio#readme
This method requires getting the OAuth app installed and approved for your GitHub repository.
-
Open draw.io in GitHub mode (https://app.diagrams.net/?mode=github)
-
Authorize with GitHub
-
Choose the file you would like to edit OR Create a diagram in a new location
-
Make changes, save and commit
-
Your svg (or png) file is now in your repo and contains a copy of your diagram in its metadata
-
In your markdown
- Reference the image like you would to any image
- On click, have the user navigate to diagrams.net and begin editing
[![Test Embedding draw.io](./Test%20Embedding.drawio.svg)](https://app.diagrams.net/#Hphilip-gai/github-drawio/main/Test%20Embedding.drawio.svg)
Reference: https://github.com/jgraph/drawio-github
- Allows you to have clickable links
- Better quality than png