Support UML diagrams in markdown with plantuml syntax

I often have the need for creating UML diagrams when explaining and discussing code, and the plantuml project (see http://plantuml.com) provides a simple syntax for creating such as text. There is a plugin for the Confluence wiki platform that support using this in wiki pages, and it would be great if github’s markdown dialect could support something similar.

214 Likes

Thanks for this feedback! We’re always working to improve GitHub and the GitHub Community Forum, and we consider every suggestion we receive. I’ve logged your feature request in our internal feature request list. Though I can’t guarantee anything or share a timeline for this, I can tell you that it’s been shared with the appropriate teams for consideration.

31 Likes

Do you have ticket accessible publicly to track PlantUML feature implementation in GitHub Markdown?

Can you please share the progress?

7 Likes

Hi @victor-letunovsky,

We do not have a public repo for this. We track our feature requests internally. As @lee-dohm mentioned, we can’t guarantee anything or share a timeline for if or when this might be implemented. 

If you’d like to keep up to date on new releases and updates to GitHub, I recommend following our blog:

https://blog.github.com/

Cheers!

1 Like

If that helps, have a look at embedding images from plantuml servers (slow but it works) :

https://stackoverflow.com/questions/32203610/how-to-integrate-uml-diagrams-into-gitlab-or-github

1 Like

Constantly getting requests for this gitlab do it, I think, but not really a fan. Would be a great help for project planning, issues etc. ATM version control the source and the PNG.

You can also try https://yuml.me/ to draw UML diagrams via markdown. For example something like this:

![Example UML](https://yuml.me/diagram/scruffy/class/[Customer]->[Billing Address])

will render into:

d8cd715f

You can edit this example at https://yuml.me/diagram/scruffy/class/edit/[Customer]->[Billing Address]

10 Likes

Just thought I’d add a note to bump this suggestion. It would be quite useful to be able to track UML changes in a the ARCHITECTURE.md file increasing transparency and community collaboration on open source software architecture.

10 Likes

I’m using plantuml proxy with asciidoc instead of markdown on github. See https://github.com/DBuret/journal/blob/master/github-adoc-puml.adoc

I agree, should be a good additional feature. Gitlab has it integrated as well and I must say it works effectivly

3 Likes

Lee,

In response to “our internal feature request list”, I offer the following user story.

User Story

As a professional software developer, I would like more transparency into the GitHub feature request process, and the opportunity to contribute open source soultions to address such feature requests.

Acceptance Criteria

  1. Feature requests for GitHub are managed in public forum, with ability to up-vote, comment and propose PRs.

  2. GitHub has a clearly defined process for accepting contributions, and adding new features to the SaaS.

Best regards,

Paul

6 Likes

Is this something that could be solved by the new features of “Github actions” ?

Thank you kindly for the outline and feedback! I’ve taken your suggestion and passed it along to the appropriate teams.
I don’t have an ETA on when or if this request will be implemented but this is in good hands.

I’d love to see this supported.

Be it using PlantUML or yUML or something else https://modeling-languages.com/text-uml-tools-complete-list/

 doesn’t matter much (yet). As long as it works :slight_smile:

3 Likes

I am also interrested in using such integration to document specifications stored in a GitHub Repository and potentially publish it to a github.io web site.

I would also like to see this added. Especially since we just moved from Gitlab to Github and Gitlab does not provide PlantUML integration on gitlab.com out of the box.

To save someone a click, the most straightforward way is ![alternative text](http://www.plantuml.com/plantuml/proxy?src=https://raw.github.com/plantuml/plantuml-server/master/src/main/webapp/resource/test2diagrams.txt) for public repos, and ![alternative text](http://www.plantuml.com/plantuml/proxy?src=https://raw.github.com/plantuml/plantuml-server/master/src/main/webapp/resource/test2diagrams.txt?token=…) for private repos (i.e. append ?token=…). 

You can get the URL with token by clicking the  Raw link when viewing the diagram file. 

However this has the major drawback of expiring the token whenever the diagram file is edited. 

1 Like

@jean wrote:

To save someone a click, the most straightforward way is ![alternative text](http://www.plantuml.com/plantuml/proxy?src=https://raw.github.com/plantuml/plantuml-server/master/src/main/webapp/resource/test2diagrams.txt

If you want to have images automatically reflect the latest version of the diagrams, it’s best to insert a flag to not use caching: e.g., 

…proxy?cache=no&src=…

1 Like

Hi.

While github developers track this feature implementation ticket internally, can somebody from dev team please share progress and ETA?

Thanks.

2 Likes

I would love to see this as well. We currently store separate .wsd files and convert them to .png using PlantUML so that we can embed them in markdown. This works, but having them rendered directly by GitHub would be great.