PlantUML Macro

Last modified by Denis Pashutkin on 2025/04/14 00:12

cogMacro and API to generate diagram images using PlantUML
TypeJAR
CategoryMacro
Developed by

Maxime Sinclair, Vincent Massol, Dennis Pashutkin

Active Installs60
Rating
1 Votes
LicenseGNU Lesser General Public License 2.1
Success

Installable with the Extension Manager

Description

This macro permits to easily generate various diagram types from a textual definition inside a wiki page, using PlantUML.

Usage

{{plantuml}}
content here...
{{/plantuml}}

The content of the macro can refer to any of the following diagram types supported by PlantUML:

  • PlantUML (diagrams starting with @startuml and ending with @enduml)
  • DITAA (diagrams starting with @startditaa and ending with @endditaa)
  • GraphViz (diagrams starting with @startdot and ending with @enddot)
  • JCCKIT (diagrams starting with @startjcckit and ending with @endjcckit)
  • Salt (diagrams starting with @startsalt and ending with @endsalt)
  • Mind maps (diagrams starting with @startmindmap and ending with @endmindmap)
  • Regexes (diagrams starting with @startregex and ending with @endregex)
  • Gantt (diagrams starting with @startgantt and ending with @endgantt)
  • Chronology (diagrams starting with @startchronology and ending with @endchronology)
  • Work breakdown structures (diagrams starting with @startwbs and ending with @endwbs)
  • EBNF (diagrams starting with @startebnf and ending with @endebnf)
  • JSON (diagrams starting with @startjson and ending with @endjson)
  • YAML (diagrams starting with @startyaml and ending with @endyaml)

For more detail see the description of the PlantUML language.

Parameters definition

NameOptionalAllowed valuesDefault valueDescription
typeyesplantuml, ditaa, dot, jcckit, salt, mindmap, regex, gantt, chronology, wbs, ebnf, json, yamlDefined in the content (see above)PlantUML Macro 2.3.0+ Defines the type of diagram when it's not specified in the content. When the type is defined in the content, it takes precedence over the parameter
formatyespng, svg or txtpng unless configured in xwiki.properties

PlantUML Macro 2.4+

Indicate the diagram output format. Motivation of using SVG format:

  • svg scales better than png;
  • svg supports hyperlinks and may be used for navigation;
  • svg is embeddable in XHTML and requires no image resource references.
titleyesStringNo title or the title defined in the contentPlantUML Macro 2.3.1+ Sets the diagram title when it's not specified in the content. When the title is defined in the content, it takes precedence over the parameter
serveryesA URL to a PlantUML serverSee below in the Configuration sectionOverrides the location of the PlantUML server, when defined.

Examples

Use Case Diagram

{{plantuml}}
@startuml
:Customer: -> (Withdraw)
note right of (Withdraw) : This is an example.
@enduml
{{/plantuml}}

Generates:

uc.png

Class Diagram

{{plantuml}}
@startuml
package "Classic Collections" #DDDDDD {
  Object <|-- ArrayList
}

package net.sourceforge.plantuml {
  Object <|-- Demo1
  Demo1 *- Demo2
}
@enduml
{{/plantuml}}

Generates:

class.png

Ditaa Diagram

{{plantuml}}
@startditaa
 Web Browser         JEE Server
 /--------\         +---------+     Database
 +--------+         |c789     |      +---+
 |c1FF    |<------->|  XWIKI  |<-=-->|{s}|
 |  Wiki  |  text   |         |      +---+
 |  page  |         +---------+
 |  with  |         |c789     |      +---+
 |diagrams|<------->|PlantUML |<-=-->|{o}|
 |        |  image  |   Server|      +---+
 \--------/         +---------+     Graphviz
@endditaa
{{/plantuml}}

Generates:

ditaa.png

PlantUML Diagram in SVG format

{{plantuml format="svg"}}
@startuml
title [[https://rendering.xwiki.org/xwiki/bin/view/Main/WebHome XWiki Rendering]] General Architecture

skinparam component {
    style rectangle
    roundCorner 20
}

file "Input Syntax" as Input
note bottom of Input 
    Examples:
    - XWiki 2.0 Syntax
    - (X)HTML
    - MediaWiki Syntax
end note

component Parser [
    [[http://www.github.com/xwiki/xwiki-rendering/tree/master/xwiki-rendering-api/src/main/java/org/xwiki/rendering/parser/Parser.java Parser]]
]

component Transformations [
    [[http://www.github.com/xwiki/xwiki-rendering/tree/master/xwiki-rendering-api/src/main/java/org/xwiki/rendering/transformation/Transformation.java Transformations]]
    (optional)
]

component Renderer [
    [[http://www.github.com/xwiki/xwiki-rendering/tree/master/xwiki-rendering-api/src/main/java/org/xwiki/rendering/renderer/Renderer.java Renderer]]
]

file Output
note bottom of Output
    Examples:
    - XHTML
    - XWiki 2.0 Syntax
end note

Input -> Parser
Parser -> Transformations : [[http://www.github.com/xwiki/xwiki-rendering/tree/master/xwiki-rendering-api/src/main/java/org/xwiki/rendering/block/XDOM.java XDOM]]
Transformations -> Renderer : XDOM'
Renderer -> Output

@enduml
{{/plantuml}}

Generates:

[[https://rendering.xwiki.org/xwiki/bin/view/Main/WebHome XWiki Rendering]] General ArchitectureXWiki RenderingGeneral ArchitectureInput SyntaxExamples:- XWiki 2.0 Syntax- (X)HTML- MediaWiki SyntaxParserTransformations(optional)RendererOutputExamples:- XHTML- XWiki 2.0 SyntaxXDOMXDOM'

Configuration

It works out of the box with all the different kinds of diagrams, using the PlantUML server available on the internet. You can also configure the macro to use your own PlantUML server that you can install on the web container used by your XWiki installation (for example). Once installed, internet access is not necessary. Another option is to leave the PlantUML server field empty, in which case the macro will use PlantUML in embedded mode (you'll then need to have GraphViz installed to generate all diagrams except for the Sequence one).

PlantUML Macro 2.0+

The PlantUML server configuration is accessible from xwiki.properties by setting the plantuml.server property. For example:

plantuml.server=http://www.plantuml.com/plantuml

It's also accessible from the Admin UI by installing the PlantUML Administration Application.

It's also possible to override the PlantUML server to use when using the macro by using the server parameter, as in:

{{plantuml server="http://www.plantuml.com/plantuml"}}
content here...
{{/plantuml}}

If a PlantUML server is specified in the Admin UI, then you can force not using any server at the level of the macro by specifying an empty server parameter, as in:

{{plantuml server=""}}
content here...
{{/plantuml}}

PlantUML Macro 2.4+

The default PlantUML diagram output format can be configured in xwiki.properties by setting the plantuml.format property. Supported values are svg, png and txt. For example:

plantuml.format=svg

The macro parameter format overrides xwiki configuration property.

The png output format is used by default if neither plantuml.format configuration property nor format macro parameter is specified.

Prerequisites & Installation Instructions

We recommend using the Extension Manager to install this extension (Make sure that the text "Installable with the Extension Manager" is displayed at the top right location on this page to know if this extension can be installed with the Extension Manager).

You can also use the manual method which involves dropping the JAR file and all its dependencies into the WEB-INF/lib folder and restarting XWiki.


If you were using version 1.1, note that the PlantUML server configuration location has changed, see above.

Release Notes

v2.4

v2.3.2

Fix source URL

v2.3.1

v2.3.0

v2.2.0

v2.1.1

v2.1

v2.0.2

v2.0.1

And also make it possible to upgrade from versions 1.x using the Extension Manager (without having to uninstall v1.x first).

v2.0

v1.1

If a previous version is installed, remove it before installing this new one.

With the new include parameter, you can include the content of the specified page at the begining of the macro content. It's similar to the !include directive of PlantUML http://plantuml.sourceforge.net/preprocessing.html
It is very useful to locate skin directives in an unique place.

v1.0

If a previous version is installed, remove it before installing this new one.

The macro works out of the box with all the different kinds of UML diagrams, using the PlantUML server available on the internet. But you can configure the macro to use your own PlantUML server.
An embedded version of PlantUML server is also available. To use it, just leave empty the Server configuration entry.

Diagrams larger than the page are now resized to avoid the horizontal scrollbar.

v0.7

Information

plantuml.jar is embedded in the macro, so is not more required to install plantuml.war.

Warning

Graphviz still required for some Diagram like Use Case diagram

v0.6

Initial version.

Dependencies

Dependencies for this extension (org.xwiki.contrib.plantuml:macro-plantuml-macro 2.4):

Get Connected