How to integrate UML diagrams into GitLab or GitHub

Question

I want to publish some programming documentation I have in a public available repository. This documentation has formatted text, some UML diagrams, and a lot of code examples. I think that GitHub or GitLab are good places to publish this.

To publish the UML diagrams, I would like to have some easy way to keep them updated into the repository and visible as images in the wiki. I don't want to keep the diagrams in my computer (or on the cloud), edit them, generate an image, and then publish it every time.

Is there a way to put the diagrams in the repository (in PlantUML syntax would be ideal), link them in the markdown text, and make the images auto-update every time the diagram is updated?

Answer 1

Edit: Alternative with Proxy service

This way is significantly different and simpler than the answer below; it uses the PlantUML proxy service:

http://www.plantuml.com/plantuml/proxy?cache=no&src=https://raw.github.com/plantuml/plantuml-server/master/src/main/webapp/resource/test2diagrams.txt

The GitHub markdown for this would be:

![alternative text](http://www.plantuml.com/plantuml/proxy?cache=no&src=https://raw.github.com/plantuml/plantuml-server/master/src/main/webapp/resource/test2diagrams.txt)

This method suffers from not being able to specify the SVG format (it defaults to PNG), and it is perhaps not possible to work-around the caching bug mentioned in the comments.

---

After trying the other answer, I discovered the service to be slow and seemingly not up to the latest version of PlantUML.

I've found a different way that's not quite as straightforward, but it works via PlantUML.com's server (in the cloud). As such, it should work anywhere you can hotlink to an image.

It exploits the !includeurl function and is essentially an indirection. The markdown file links to a PlantUML source that includes the diagram's source. This method allows modifying the source in GitHub, and any images in the GitHub markdown files will automatically update. But it requires a tricky step to create the URL to the indirection.

1. Get the URL to the raw PlantUML source, e.g., https://raw.githubusercontent.com/linux-china/plantuml-gist/master/src/main/uml/plantuml_gist.puml (using the example in the joanq's answer)

2. Go to http://plantuml.com/plantuml/form (or PlantText.com) and create a one-line PlantUML source that uses the !includeurl URL-TO-RAW-PLANTUML-SOURCE-ON-GITHUB operation. Continuing with the example URL, the PlantUML (meta)source is:

   !includeurl https://raw.githubusercontent.com/linux-china/plantuml-gist/master/src/main/uml/plantuml_gist.puml
   

3. Copy the image URL from PlantUML.com's image, e.g., http://plantuml.com:80/plantuml/png/FSfB2e0m303Hg-W1RFPUHceiDf36aWzwVEl6tOEPcGGvZXBAKtNljW9eljD9NcCFAugNU15FU3LWadWMh2GPEcVnQBoSP0ujcnS5KnmaWH7-O_kEr8TU and paste it into your GitHub markdown file. This URL won't change.

   ![PlantUML model](http://plantuml.com:80/plantuml/png/3SNB4K8n2030LhI0XBlTy0YQpF394D2nUztBtfUHrE0AkStCVHu0WP_-MZdhgiD1RicMdLpXMJCK3TC3o2iEDwHSxvNVjWNDE43nv3zt731SSLbJ7onzbyeF)
   

Bonus: You can even get access to the SVG format by modifying the plantuml/png/ part of the URL to be plantuml/svg/ as follows

![PlantUML model](http://plantuml.com:80/plantuml/svg/3SNB4K8n2030LhI0XBlTy0YQpF394D2nUztBtfUHrE0AkStCVHu0WP_-MZdhgiD1RicMdLpXMJCK3TC3o2iEDwHSxvNVjWNDE43nv3zt731SSLbJ7onzbyeF)

Example on GitHub

https://github.com/fuhrmanator/course-activity-planner/blob/master/ooad/overview.md

Caveat with private repos

As davidbak pointed out in a comment, the raw file in a private repo will have a URL with token=<LONGSTRINGHERE> in it, and this token changes as the source file updates. Unfortunately, the markdown breaks when this happens, so you have to update the Readme file after you commit the file to GitHub, which is not a great solution.

Answer 2

This is an old question, but it comes up early in the searches for solutions to this problem.

UPDATE

GitLab now support both Mermaid and PlantUML diagrams on their public offering. Mermaid is supported out of the box.

```mermaid
sequenceDiagram
Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response
Alice -> Bob:Another authentication Response
Bob --> Alice: Another authentication Response
```

Example

Orig Answer

The other answers discuss GitHub, but it is worth noting that GitLab has native integration for this, if you are deploying in-house. For some reason, they have never activated the feature on their public offering. There are tickets open to activate the feature.

If you are working of an in-house hosted solution, there are instructions available in the administration documentation

Basically you

1. stand up your own plantuml server
2. check the Enable PlantUml in GitLab server configuration
3. write PlantUml in your markdown

```plantuml
Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response
   
Alice -> Bob: Another authentication Request
Alice <-- Bob: Another authentication Response
```

Answer 3

I found it is possible to do this using plantuml-gist on http://uml.mvnsearch.org/

Just put a valid puml file in the repository and include a link to this site in the documentation.

For example, for the file https://github.com/linux-china/plantuml-gist/blob/master/src/main/uml/plantuml_gist.puml in GitHub, you would use http://uml.mvnsearch.org/github/linux-china/plantuml-gist/blob/master/src/main/uml/plantuml_gist.puml as your link.

Here's what it looks like linked in StackOverflow:

UML image http://uml.mvnsearch.org/github/linux-china/plantuml-gist/blob/master/src/main/uml/plantuml_gist.puml

Unfortunately, it doesn't seem to work with GitLab. I always get a "No PUML file found", even though I have checked the path several times.

EDIT: server at uml.mvnsearch.org seems down.

Answer 4

For Gitlab
Step 1: To enable the PlantUML and insert the PlantUML server location Step 2: To create a PlantUML example and then you will see the result on the preview

@startuml
Bob -> Alice : hello
@enduml

For GitHub
Step 1: To create a PlantUML file

@startuml
Bob -> Alice : hello
@enduml

Step 2: Get a URL from raw in my example: "https://raw.githubusercontent.com/williehao/nginx-certbot/main/nginx-certbot.iuml" Step 3: Integrate PlantUML render engine with GitHub markdown

![your-UML-diagram-name](http://www.plantuml.com/plantuml/proxy?cache=no&src=https://raw.githubusercontent.com/williehao/nginx-certbot/main/nginx-certbot.iuml)

PS: replace your own raw URL from "https://raw.githubusercontent.com/williehao/nginx-certbot/main/nginx-certbot.iuml" to ****

reference

Answer 5

To publish the UML diagrams, I would like to have some easy way to keep them updated into the repository and visible as images in the wiki

This should be possible on GitHub now (Aug. 2022)

Wikis now support math and Mermaid diagrams

Earlier this year (Feb. 2022), GitHub added support for LaTeX style mathematical expressions and Mermaid diagrams in Markdown.

However, until now, GitHub wikis were missing this support.
You can now use these formatting features in GitHub wikis.

For more information about using mathematical expressions and Mermaid with GitHub, see creating diagrams and writing mathematical expressions in the GitHub documentation.

Those diagrams includes ULM ones.

Answer 6

Since GitLab supports rendering PlantUML out of the box, you can use the following:

README.md

This is some example text in a Markdown file. Followed by a PlantUML diagram, loaded from an URL.

```plantuml
!include https://gitlab.com/my-drawing.puml
```

When you 'preview' the file, it will render the text together with an image of the PlantUML diagram.

For more information about PlantUMLs !include directive, see https://plantuml.com/preprocessing#393335a6fd28a804

Answer 7

GitLab

Already support PlantUML natively as mentioned in other posts.

GitHub

I wish they support it natively too, but they don't at the moment.

Workaround

I built my own workaround similar to the PlantUML proxy mentioned above, but a little bit better.

TLDR:

• Example: https://puml-demo.herokuapp.com/github/ghe/lyang/puml-demo/blob/master/README.md
• Source Code: https://github.com/lyang/puml

Long:

• It supports arbitrary urls
• It supports both public and private repos on https://github.com
• It supports GitHub Enterprise instances
• It does not expose API tokens as part of the URL like the PlantUML proxy solution
• It can be used outside of GitHub, e.g. in emails, wiki, presentation etc.
• Private repos and GHE instances needs your own puml app with API token configured.
• Examples can be found in https://github.com/lyang/puml

Answer 8

Good news regarding GitHub!

Just found out, that for Github - Mermamid graphs are nativly supported now within GitHub Issues, GitHub Discussions, pull requests, wikis, and Markdown files.

Just put your graph definition to your Markdown file.

Here is a simple flow chart:

```mermaid
graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;
```

• Flow chart example pic
• See https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams for details.
• Here you find a working example https://gist.github.com/dirksan28/b270aacc5eb07a0c7b1bc75f5fbd24e3 on GitHub

Answer 9

Sharing my open source project that handles all this for you https://github.com/danielyaa5/puml-for-markdown

How It Works

Using PlantUML Web Service to Render PUML Diagrams

You can use PlantUML using the online web service to generate images on-the-fly. A online demonstration is available at http://www.plantuml.com/plantuml. You can pass the encoded text of your diagrams to the web service in the url path and it will generate an SVG or PNG for you. Here's a simple HelloWorld example http://www.plantuml.com/plantuml/uml/Aov9B2hXil98pSd9LoZFByf9iUOgBial0000. Large diagrams will have very long encoding strings, they can exceed maximum url length. They also don't look very good in markdown files. By default the CLI will use the tinyurl.com service to shorten the link to the diagram.

Encoding PUML Diagrams for the Web Service

The CLI will use the plantuml-encoder package to encode puml files. To support hyperlinking diagrams we need to parse all hyperlinks in the puml files. A dependency graph is created for the files and a DFS is performed where we create links for the leaf nodes first, then replace the links in the parent nodes with the links to the leaf nodes. The puml files are not actually modified, only the puml files content in memory is modified. By default the tinyurl free service is used to shorten the links.

In order to support !include we parse puml files and replace any !include with the contents of the file referenced.

Parsing Markdown

The markdown files are then parsed for markdown comments. If the comments reference a PlantUML file, a link to the web service url will be added next to the comment. Because these links contain the full PlantUML diagram encoding in it, there are no issues using them in private repositories.

Answer 10

Sharing my OSS project you are welcome to try: plantaznik, it is a Rust CLI tool for inlining PlantUML links. You can install it via cargo (cargo install plantaznik) or download prebuild libraries in releases.

Just place the following macros to your README:

<!-- plantaznik:./path/to/plantuml/source.plantuml -->
![](???)

And run:

$ plantaznik README.md

You can easily use it for multiple files, in your git hooks or CI. See readme for more examples.