Skip to content

Use diagrams.net (draw.io) diagrams in your GitHub markdown files. View diagrams, edit, commit, use PRs and get live updates in your repo.

License

Notifications You must be signed in to change notification settings

philip-gai/github-drawio-demo

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

24 Commits
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Embedding Diagrams in GitHub Markdown

This explains and demos how to use diagrams.net (draw.io) diagrams in your GitHub repo.

Benefits of using diagrams.net in GitHub repositories

  1. Diagrams are stored in your repository with your code and docs
  2. Diagram access is controlled by GitHub repository access
  3. Diagrams are version-controlled using git
  4. Create PRs with diagram updates to get approvals and feedback
  5. One-click diagram editing from your GitHub repository
  6. diagrams.net is open-source: https://github.com/jgraph/drawio

How to integrate diagrams.net (draw.io) with your GitHub repo

Note: Images in markdown are cached and can take five minutes to update

Using VS Code locally, on github.dev or on CodeSpaces (Recommended)

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.

  1. Open the repository you want to create the diagram in
  2. Press . to open github.dev (or use Codespaces, or clone and use VS Code locally)
  3. Install the Draw.io Visual Studio Code extension
  4. 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.
  5. Reference the file using a relative link in markdown like you would reference any file ![Label](relative link)
  6. 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

Draw.io Extension Demo

Using app.diagrams.net

This method requires getting the OAuth app installed and approved for your GitHub repository.

  1. Open draw.io in GitHub mode (https://app.diagrams.net/?mode=github)

  2. Authorize with GitHub

    • Authorize GitHub
  3. Choose the file you would like to edit OR Create a diagram in a new location

    • File should be editable bitmap image png or svg
    • Authorize GitHub
    • Create diagram screenshot
  4. Make changes, save and commit

  5. Your svg (or png) file is now in your repo and contains a copy of your diagram in its metadata

  6. In your markdown

    1. Reference the image like you would to any image
    2. 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

GitHub App Demo

Real Examples

SVG

  • Allows you to have clickable links
  • Better quality than png

Test Embedding draw.io

PNG

Test Embedding draw.io

About

Use diagrams.net (draw.io) diagrams in your GitHub markdown files. View diagrams, edit, commit, use PRs and get live updates in your repo.

Topics

Resources

License

Stars

Watchers

Forks

Sponsor this project