[craig0990]

I've actually just tried something similar for work (we'll see how it goes).

Take Material for MkDocs with the "mermaid2" and "plantuml-markdown" plugins, a custom plugin to inline SVG diagrams [1], and "mike" for versioning.

This gets us a Git repo where anyone can draw and contribute diagrams with either Mermaid, PlantUML, or Draw.io diagrams embedded in SVG. Hosted in GitLab Pages for access control.

All three diagram formats support hyperlinks in their outputs, so we're aiming for a clickable, "zoom-able" adaptation of the C4 Model [2].

It's a bit fiddly to get going, but quite nice and easy to work with afterwards, provided individuals can commit time to updating the diagrams.

In principle, GitLab supports PlantUML with extra config, and SVG embeds, but in practice we can't yet commit to updating our self-hosted GitLab, and the SVG embed is aggressively filtered - so Draw.io embeds often show up blank. MkDocs solves the "make it pretty, browseable, and searchable" aspect. Git and "mike" solve the "what was the original design again?" aspect.

I'm tempted to write the approach up, but I broke my blog - perhaps I should rebuild it with Material for MkDocs :)

The Material for MkDocs Insiders program gets you nice extras (mermaid support built-in, stay-on-same-page across "mike" versions, and more) [3]

[1] https://pypi.org/project/mkdocs-plugin-inline-svg/

[2] https://c4model.com/

[3] https://squidfunk.github.io/mkdocs-material/insiders/

(edit: typos)

[hyperman1]

Thanks. This is an alternative vision compared with what I am doing, but it seems better. Especially the C4 model as basic philosophy, and then the supporting technology.

Pleas blog about this, it is very interesting to me.

Just to be sure: this is what you mean with Mike?

https://github.com/jimporter/mike

[craig0990]

Yep, that's the one - the versioning was more important to me than it might be to others (even internally). mike was a bit confusing to set up in CI since it re-commits the build back to a branch (imagine the loops you could get yourself into) but the output is nice.

We're not strict about C4 (we actually created an alternative-but-similar flow incidentally) - but C4 to me is a nice diagrammatic principle of "Don't Repeat Yourself" - draw a box, label it, and link to that system's diagram instead.

I could go on for pages / hours :D I'm a bit over-passionate about documentation. Email's in my profile, FWIW.

[chrisweekly]

Thanks, this is similar to what I have started to work on. Note GitLab supports a Kroki integration, which is a powerful way to enable "all the things" wrt diagramming libs.