Markdown with PlantUML

README.md

How to use PlantUML with Markdown

PlantUML is a really awesome way to create diagrams by writing code instead of drawing and dragging visual elements. Markdown is a really nice documentation tool.

Here's how I combine the two, to create docs with embedded diagrams.

Step 0: Setup

Get the command-line PlantUML from the download page or your relevant package manager.

Step 1: Create a Markdown file

Use your favorite markdown or text editor. Most (if not all) developer-oriented text editors have some kind of markdown support.

Remember that md files can contain html, and that html is passed-through to the generated html as-is.

When you want to embed a diagram, create a hidden div: <div hidden>.

Now start a code block by indenting or typing 3 backticks. The first line of the code block must be @startuml followed by a file name (with no extension). The following lines should be the actual diagram code, ending with @enduml. End the code block and close the div.

Finally, to actually show the diagram in the document, add an image in markdown: ![](firstDiagram.svg). The name must be the same name as in the @startuml command, with a .svg extension.

All together now

Regular **Markdown** here.

<div hidden>
```
@startuml firstDiagram

Alice -> Bob: Hello
Bob -> Alice: Hi!
		
@enduml
```
</div>

![](firstDiagram.svg)

Some more markdown.

Step 2: Run PlantUML on the Markdown file

On the command line:

plantuml -tsvg FILENAME

Where FILENAME is the name of the markdown file.

For every PlantUML block in the file, one svg diagram is generated. When the markdown to html converter is running, the html will contain image links to the generated images.

Step 3: Convert locally to HTML or upload to GitHub

If you host the files in GitHub (or other services that convert md to html on the fly), the last step is uploading or pushing the files. Make sure to include everything: the markdown and the generated diagrams.

Otherwise, use your favorite tool for converting markdown to html - a markdown editor or a command line tool.

firstDiagram.svg

sample.md

Regular Markdown here.

@startuml firstDiagram

Alice -> Bob: Hello
Bob -> Alice: Hi!

@enduml

Some more markdown.

Hello noamtamim,

Thank you for writing this! 😄

If you don't want to show the "PlantUML" syntax on github, you can replace <div hidden></div> with inline commenting <!-- -->. PlantUML will still generate the UML.

As for your example:

Regular **Markdown** here.

<!--
@startuml firstDiagram

Alice -> Bob: Hello
Bob -> Alice: Hi!
	
@enduml
-->

![](firstDiagram.svg)

Some more markdown.

Thanks @sjoulbak, that's indeed more compact.

You can put the PlantUML in a separate file, MyModel.puml and link to it in a Readme using this method. It renders the UML using the web service, rather than having to install PlantUML on a machine and doing an extra step.

Note that this doesn't work well in private repos, because the link to the raw .puml file has a token that tends to change when the repo evolves.

One issue with the HTML comment strategy is you can't use dotted lines, -->.

I tried:

<!--
```
@startuml
Foo --> Bar
@enduml
```
-->

As well as:

<!--
    @startuml
    Foo --> Bar
    @enduml
-->

The former seemed to break the markdown engine (the Marked 2 app) by never closing the first comment at all, the latter still rendered the dotted line as a closing comment. Oh well.

I ended up separating the markdown and the plantuml with a README.md and a README.plantuml, but still using the filename trick shown here. Thanks!

One issue with the HTML comment strategy is you can't use dotted lines, -->.

I logged a bug/feature request for PlantUML at https://forum.plantuml.net/11806/dashed-arrow-also-the-close-comment-blocks-html-xml-markdown -- the maintainer often does quick fixes if it's simple and a popular use case, so we'll see.

@woahdae I solved this by changing the arrow to the other direction:

<!--
@startuml firstDiagram
Bar <-- Foo	
@enduml
-->

@sjoulbak both the workaround suggested in the forum and the actual solution work just fine. Changing arrow direction works, but changes semantics/readability too.
The fix has another advantage: it also works in component diagrams:

http://www.plantuml.com/plantuml/uml/SoWkIImgAStDuOfsZ5NGjLE8Tehb0c85NTru8CSvbiiXDIy5A0y0

awesome!!! Thanks

In my case, I use the plantuml-extension. This chrome extension renders the plantuml code into image.

I am using https://github.com/verhas/jamal Jamal as a preprocessor for Markdown and also to Asciidoc files.
Release 1.6.5 is due in a few days and will contain a PlantUml module.

Using this workflow is somewhat similar to running plantuml extracting the images from the markdown file. It can also use other macro features, include sample codes from the code, fetch parameters and insert into the documentation from project XML files (typically the current version of the documented project). This approach does not have the

<!--
....
    A --> B
-->

As the output file, which is a native Markdown, Asciidoc, whatever format you use, does not contain the UML text anymore.

I wrote a CLI tool that embeds interactive PUML diagrams to your github markdown files by converting links in your markdown https://github.com/danielyaa5/puml-for-markdown

@danielyaa5 Nice! Thanks for sharing.

awesome! thanks!

Hey, I follow your step, but when i execute java -jar /path/to/plantuml.jar -tsvg index.md . I got : "No diagram found"

My plumtuml version is "plantuml-1.2023.4.jar".

Hey, I follow your step, but when i execute java -jar /path/to/plantuml.jar -tsvg index.md . I got : "No diagram found"

My plumtuml version is "plantuml-1.2023.4.jar".

This error usually means the @startuml and @enduml are not found surrounding the diagram. You can verify that in your markdown file.

My approach is to use a code block with language plantuml (then the vscode extensionPlantUML renders it in the preview)
and replace the code block with an image at build time.

See https://gist.github.com/neumantm/bca0e942859f73db59cd273e5e13f5a3

I created a GitHub Actions to deploy Markdown with PlantUML using Material MkDocs directly to GitHub Pages:
https://github.com/Maagan-Michael/mm-portal/actions/workflows/publish.yml

<details></details> could possibly be your help

Regular **Markdown** here.

![[firstDiagram.png]]
<details>

```
@startuml firstDiagram

Alice -> Bob: Hello
Bob -> Alice: Hi!
		
@enduml
```

</details>

Some more markdown.

$ plantuml -t svg README.md

$ plantuml --version
PlantUML version 1.2023.11 (Thu Sep 14 03:26:33 JST 2023)
(GPL source distribution)
Java Runtime: OpenJDK Runtime Environment
JVM: OpenJDK 64-Bit Server VM
Default Encoding: UTF-8
Language: en
Country: JP

PLANTUML_LIMIT_SIZE: 4096

Dot version: dot - graphviz version 9.0.0 (20230911.1827)
Installation seems OK. File generation OK

Wtih Obsidian