PlantUML diagrams

Writerside 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 left to right direction class User { id : INTEGER .. other_id : INTEGER } class Email { id : INTEGER .. user_id : INTEGER address : INTEGER } User::id *-- Email::user_id @enduml

For more examples of class diagrams, see https://plantuml.com/class-diagram

Use case diagram

@startuml User << Human >> :Main Database: as MySql << Application >> (Start) << One Shot >> (Use the application) as (Use) << Main >> User -> (Start) User --> (Use) MySql --> (Use) @enduml

For more examples of use case diagrams, see https://plantuml.com/use-case-diagram

JSON data

@startjson { "fruit":"Apple", "size":"Large", "color": ["Red", "Green"] } @endjson

For more examples of JSON data diagrams, see https://plantuml.com/json

Gantt chart

@startgantt [Prototype design] requires 15 days [Test prototype] requires 10 days -- All example -- [Task 1 (1 day)] requires 1 day [T2 (5 days)] requires 5 days [T3 (1 week)] requires 1 week [T4 (1 week and 4 days)] requires 1 week and 4 days [T5 (2 weeks)] requires 2 weeks @endgantt

For more examples of Gantt charts, see https://plantuml.com/gantt-diagram

Mind map

@startmindmap * root node * some first level node * second level node * another second level node * another first level node @endmindmap

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 a CDATA section to interpret it literally or use character references: < and >.

                            <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 &lt;&lt; Human &gt;&gt;
                            @enduml

                            </code-block>
                        

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".

                            <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>
                        

Last modified: 11 November 2024