This plugin converts PlantUML files.

The default configuration will output all *.puml files found under the plantuml dir as SVG files.

Developed against PlantUML version 1.2020.24. Probably works with some earlier versions.

Unicode

The plugin expects PlantUML files to be encoded with UTF-8.

Known Issues

• It's slow! Every PlantUML rendering launches a new Java process, on my laptop it takes 4-8 seconds per file. I have some ideas to speed this up, and they may be available in future plugin versions.

• Changes to files included via !include ... or via a pattern (e.g. -Ipath/to/*.iuml) will NOT trigger a rebuild. Instead, if you include them explicitly in PLANTUML_ARGS (e.g. -Ipath/to/foo.iuml) then they will trigger a rebuild.

• nikola auto does not watch dirs in PLANTUML_FILES or files included via PLANTUML_ARGS / !include. As a workaround you could put PlantUML files under any dir listed in POSTS or PAGES because those dirs are watched. (Use .iuml suffix for include files to prevent them matching the *.puml wildcard in PLANTUML_FILES)

• If your file does not begin with @start then PlantUML prepends a line containing @startuml which causes the line number in error messages to be one higher than the actual error location.

• The file name in PlantUML error messages is always string rather than the actual problem file. PlantUML does this when input is piped via stdin, which as a compromise for simplicity we always do.

Suggested Configuration:

#
# PLANTUML_EXEC (list of strings) - The command to run PlantUML
#
# '%site_path%' anywhere in PLANTUML_EXEC will be replaced with the full path to the site dir.
# PlantUML is run in the site dir so often this is not needed.
#
# Examples
# --------
# Run from a JAR file:
#   [ 'java', '-Djava.awt.headless=true', '-jar', 'plantuml.jar' ]
#
# Run in Docker:
#   [ 'docker', 'run', '--interactive', '--rm', '--volume', '%site_path%:/work', 'YOUR_IMAGE',
#     'java', '-Djava.awt.headless=true', '-jar', 'plantuml.jar' ]
#
PLANTUML_EXEC = ['plantuml']

#
# PLANTUML_ARGS (list of strings) - CLI arguments that are sent to PlantUML when rendering PlantUML files,
# see https://plantuml.com/command-line
#
# Examples
# --------
# Use a common style file for all diagrams:
#   [ '-Imy_plantuml_style.iuml' ]
#
# Specify the style in conf.py
#   [ '-chide footbox', '-SShadowing=false' ]
#
PLANTUML_ARGS = []

#
# PLANTUML_FILES contains (wildcard, destination, extension, args) tuples.
#
# <wildcard> is used to generate a list of source files in the same way as POSTS and PAGES.
#
# Rendered files will be placed at:
#   output / <destination> / <filename><extension>
#
# As with POSTS and PAGES you can create any directory structure you want and it will be reflected in the output.
#
# <args> is a list of cli arguments that are appended to PLANTUML_ARGS
#
PLANTUML_FILES = (
    ('plantuml/*.puml', 'plantuml', '.svg', ['-tsvg']),
)

#
# PLANTUML_CONTINUE_AFTER_FAILURE (boolean) - If True then Nikola will continue executing after any PlantUML failures.
#
# PlantUML puts its error messages in the rendered output so you might find this option helpful when running `nikola auto`.
#
PLANTUML_CONTINUE_AFTER_FAILURE = False

#
# PLANTUML_DEBUG (boolean) - Control plugin verbosity
#
PLANTUML_DEBUG = False

Requirements:

• PlantUML (Third-Party software)

Issues? Questions?

You can report issues with this plugin and request help via GitHub Issues.