How to integrate UML diagrams into GitLab or GitHub
Solution 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.
-
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) -
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
-
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.
Solution 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
```
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
- stand up your own plantuml server
- check the
Enable PlantUml
in GitLab server configuration - write PlantUml in your markdown
```plantuml
Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response
Alice -> Bob: Another authentication Request
Alice <-- Bob: Another authentication Response
```
Solution 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:
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.
Solution 4
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
Related videos on Youtube
joanq
Updated on March 15, 2022Comments
-
joanq about 2 years
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?
-
Fuhrmanator over 8 yearsThis would be even cooler if you showed an example in gollum wiki markup, but it's good enough to figure it out.
-
Fuhrmanator over 8 yearsIt appears the server that uml.mvnsearch.org is using doesn't grok the latest PlantUML language. I posted an answer that uses PlantUML.com's cloud server.
-
Fuhrmanator over 8 yearsI'm not sure it's perfect, because GitHub caches images from
.md
files in its camo.githubusercontent.com site. I currently have a use-case diagram I updated, but the updates didn't get to the.md
file after several days, even when I updated other parts of the.md
file. I may have to touch the parts that refer to the image. YMMV. -
Fuhrmanator over 8 yearsIndeed, GitHub seems to only update its cached
camo
site images when the URL changes to the image. A way to update the URL without actually changing it is to add/remove.svg
(or.png
if you're using that format). PlantUML doesn't care if you have that extension at the end, but GitHub will think you changed the URL and update its cache incamo.
. See github.com/fuhrmanator/course-activity-planner/commit/… for details. -
joanq over 8 yearsI don't think that GitLab is caching images the same way, so there shouldn't be a problem in my case, but it's good to know how to solve it just in case.
-
mjs over 7 years@joanq emedded image link possibly broken
-
ilya1245 almost 7 yearsto avoid caching just add some parameter to the url e.g. plantuml.com/plantuml/proxy?src=https://raw.github.com/plantuml/… and increment it each time the uml file(test2diagrams.txt) is modified
-
hal about 5 yearsTo avoid caching
cache=no
url parameter should be added: plantuml.com/plantuml/proxy?cache=no&src=https://… -
Fuhrmanator about 5 years@hal The caching problem is with GitHub and not PlantUML, so I'm not sure how that cache flag helps.
-
hal about 5 years@Fuhrmanator, caching problem is always browser issue, not GitHub or PlantUML. When you use
cache=no
url parameter, PlantUML server will setCache-Control: no-cache
header, so browser will not put the image to cache. When you press F5 in browser, new request for the image will be made to PlantUML server. If you pass github url to master branch assrc
(not specific comment), then PlantUML will request latest version of file and will return updated image. -
Martin Dürrmeier about 5 yearsis there a way to make this for for private repos too?
-
davidbak over 4 years"Alternative with Proxy Service" works great. The way to get it to work with private repos is to include the
?token=<LONGSTRINGHERE>
as part of the raw url. Unfortunately, that token changes with every edit of the plantuml source, so you have to work a bit to keep the markdown doc up-to-date. But it is doable. -
Fuhrmanator over 4 years@hal OK - I updated the answer for the
cache=no
feature. It's important to note that it does take some time for the image to update when the plantuml source is changed. I found some hints at github.com/atom/markdown-preview/issues/… -
Jesse about 4 yearsgitlab.com supports plantuml now, and test fine. Please to ref gitlab-plantuml
-
Jefferey Cave about 4 years@Jesse I almost consider that irrelevant given Mermaid support, but plantUML still covers more use cases. Either way, good to hear.