Embed diagrams (e.g. draw.io schematics as xml files) by reference in markdown

user_3102638 0
Viewed 4105

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.

markdown diagram xml
1 Answers

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.

user_24692010
Related