10

In my workflow I use both git (GitLab on a private server) and draw.io (or diagrams.net as it has been renamed).
I wonder what's the best way to start versioning diagrams as well as code, and embed them in the markdown documentation.

I saw that it is possible to version a single diagram by exporting it to uncompressed xml. Now, ideally what I would like is a flow like this:

  • edit diagram on the native app
  • version diagram by exporting as xml
  • embed in .md docs by reference

In other words, I would love to not have a jpeg/png version of the diagram and yet still having it rendered in markdown. Is this even possible?

I found this support page Embed a diagram in GitHub markdown, but it seems to be not what I'm looking for:

  • opens an embedded editor
  • i don't think it will worjk with private gitlab severs?

Any suggestion (even involving different tools) would be much appreciated.

a_bet
  • 370
  • 3
  • 14

2 Answers2

5

I use Draw.io diagrams with GitLab / markdown on a internet independent self hosted scenario. I use both the Ubuntu snap app and a docker image.

If you save the Draw.io diagrams as "Editable SVGs" (I like to use the extension .drawio.svg to make it obvious) then it saves any required metadata within the SVG file.

This means the image size is minimal, and CI pipelines can still convert the file to PNG if at all required. And the SVG can be directly included in markdown without having to export every time.

GitLab can also allow you to "spot the difference" between the images for merge requests.

Workflow:

git checkout -> open *.drawio.svg file in draw.io website or app -> make changes -> Save -> merge request.

Lii
  • 11,553
  • 8
  • 64
  • 88
ben5756
  • 366
  • 2
  • 6
  • I also use the `.drawio.svg` approach (with the great [VSCode drawio extension](https://marketplace.visualstudio.com/items?itemName=hediet.vscode-drawio) on Windows/WSL), but found merging not to be optimal. The drawio metadata (mxfile) in the svg file is compressed. The actual svg part is human readable/mergeable, but I've found that a small change can change almost all lines, probably because it's autogenerated from scratch. – Martin Thøgersen Apr 22 '21 at 20:50
  • Also see https://stackoverflow.com/questions/66262620/merge-changes-on-draw-io-diagrams-net-files-with-git/67220405#67220405 – Martin Thøgersen Apr 22 '21 at 20:51
1

You can check out GitLab 15.10 (March 2023, which includes:

Create diagrams in wikis by using the diagrams.net editor

With GitLab 15.10, you can more easily create and edit diagrams in wikis by using the diagrams.net GUI editor.
This feature is available in the Markdown editor and the content editor, and was implemented in close collaboration with the GitLab wider community.

diagrams.net

See Documentation and Issue.

VonC
  • 1,262,500
  • 529
  • 4,410
  • 5,250