PlantUML diagrams
Last modified: 11 November 2024Writerside supports adding diagrams using PlantUML. Besides various UML diagrams, you can visualize JSON and YAML, create Gantt charts and mind maps, and many other types of diagrams.
To add a PlantUML diagram, use a code block with the language set to plantuml
:
<code-block lang="plantuml">
@startuml
Bob->Alice : Hello!
@enduml
</code-block>
```plantuml
@startuml
Bob->Alice : Hello!
@enduml
```
The result will look as follows:
Reference PlantUML diagram from file
If you have a file with PlantUML code, you can reference it instead of copying the PlantUML code into the code block. For more information, see Reference code from file.
<code-block lang="PlantUML" src="graph.puml"/>
```PlantUML
```
{ src="graph.puml" }
Or via a relative path:
<code-block lang="PlantUML" src="../codeSnippets/graph.puml"/>
```PlantUML
```
{ src="../codeSnippets/graph.puml" }
Examples
Here are a couple of examples:
Class diagram
@startuml
{...}
For more examples of class diagrams, see https://plantuml.com/class-diagram
Use case diagram
@startuml
{...}
For more examples of use case diagrams, see https://plantuml.com/use-case-diagram
JSON data
@startjson
{...}
For more examples of JSON data diagrams, see https://plantuml.com/json
Gantt chart
@startgantt
{...}
For more examples of Gantt charts, see https://plantuml.com/gantt-diagram
Mind map
@startmindmap
{...}
For more examples of mind maps, see https://plantuml.com/mindmap-diagram
Troubleshooting
Here are some possible issues that you might encounter and how to fix them:
- Cannot find Graphviz
In the rendered output, you see the following message:
Dot Executable: /opt/local/bin/dot Dot executable does not exist Cannot find Graphviz. You should try @startuml testdot @enduml or java -jar plantuml.jar -testdot
PlantUML uses Graphviz/DOT to compute node positioning for some UML diagrams. If you see the previous message in your rendered output, it means that the machine where you are building the topic files does not have Graphviz.
Install Graphviz as described in the installation guide.
- Syntax Error
For XML topics or when using semantic code blocks in MD topics, make sure there are no
<
and>
characters in the PlantUML code. You can either wrap the whole contents of the code block in aCDATA
section to interpret it literally or use character references:<
and>
.Broken syntaxWrap with CDATAUse references<code-block lang="plantuml"> @startuml User << Human >> @enduml </code-block>
<code-block lang="plantuml"> <![CDATA[ @startuml User << Human >> @enduml ]]> </code-block>
<code-block lang="plantuml"> @startuml User << Human >> @enduml </code-block>
tip
Writerside has an action to wrap the contents of a code block with
CDATA
: put the caret in a code block, press AltEnter, and select Wrap inner elements with CDATA.- No variables
By default, Writerside ignores variables in PlantUML code and renders them literally. If you want to add something like a version via a variable defined in your project, set
ignore-vars="false"
.Variables ignored by defaultVariables properly resolved<var name="v1" value="1.0"/> <var name="v2" value="2.0"/> <code-block lang="plantuml"> @startuml [Component] --> "Interface %v1%" [Component] --> "Interface %v2%" @enduml </code-block>
<var name="v1" value="1.0"/> <var name="v2" value="2.0"/> <code-block lang="plantuml" ignore-vars="false"> @startuml [Component] --> "Interface %v1%" [Component] --> "Interface %v2%" @enduml </code-block>
Thanks for your feedback!