Render a PlantUML diagram in an asciidoc readme in GitLab

Question

I'm trying to put my diagrams in the readme and from looking at the gitlab docs it seems like it can be done by default. However, GitLab doesn't render my diagrams.

I used the same method as in the example in the docs and also tried this:

[plantuml, format="png", id="UseCase", width="200px"]
plantuml:Diagrams/UseCase.puml[]

This renders just plantuml::Diagrams/BookHubUseCase.puml[].

The GitLab example with the code block renders just the code block.

How can I render these diagrams in my README? I want to avoid having to have pngs in the repo and setting up CI to render them on change.

Answer 1

According to the docs, PlantUML integration is enabled by default only for SaaS GitLab:

With the PlantUML integration, you can create diagrams in snippets, wikis, and repositories. This integration is enabled on GitLab.com for all SaaS users and does not require any additional configuration.

So if you are using SaaS solution - you can create support request in this situation.

If you are using self-managed GitLab instance - your administrators have to configure PlantUML server first and then enable the integration. You can try to check if PlantUML is available by accessing the https://your.gitlab.com/-/plantuml/ url, but this may not work in all cases. The easiest way will be to clarify with your administrators if PlantUML integration is enabled or not.

Answer 2

To render the PlantUML diagram locally, you can use my Jamal preprocessor that has support for PlantUML natively before 2.5.0 and via Kroki following that version.

That way, you get an adoc file that references a PNG or SVG file during the editing, and it will render properly on any platform.

DISCLAIMER: I wrote Jamal; it is open source, available from Maven central as well as from https://github.com/verhas/jamal

For example, can edit your README.adoc.jam in IntelliJ or AsciidocFX, and the Acsiidoc preprocessor version of Jamal installed will continuously create the SVG or PNG file when needed and save the processed file into README.adoc containing the reference to the image.