A PlantUML plugin for Markdown
This plugin implements a block extension that can be used to specify a PlantUML diagram that will be converted into an image and inserted into the document.
Syntax:
::uml:: [format="png|svg|txt"] [classes="class1 class2 ..."] [alt="text for alt"] [title="Text for title"] [width="300px"] [height="300px"]
PlantUML script diagram
::end-uml::
Example:
::uml:: format="png" classes="uml myDiagram" alt="My super diagram placeholder" title="My super diagram" width="300px" height="300px"
Goofy -> MickeyMouse: calls
Goofy <-- MickeyMouse: responds
::end-uml::
The GitLab/GitHub block syntax is also recognized. Example:
```plantuml id="myDiag" format="png" classes="uml myDiagram" alt="My super diagram placeholder" title="My super diagram" width="300px" height="300px"
Goofy -> MickeyMouse: calls
Goofy <-- MickeyMouse: responds
```
Options are optional (otherwise the wouldn't be options), but if present must be specified in the order
id
, format
, classes
, alt
, title
, width
, height
, and source
.
The option value may be enclosed in single or double quotes.
Supported values for format
parameter are:
png
: HTML img
tag with embedded png imagesvg
: HTML img
tag with embedded svg image (links are not navigable)svg_object
: HTML object
tag with embedded svg image (links are navigable)svg_inline
: HTML5 svg
tag with inline svg image source (links are navigable, can be manipulated with CSS rules)txt
: plain text diagrams.The width
and height
options must include a CSS unit.
source
parameter is used for inclusion of an external source diagram instead on an inline code. Here's an example in
GitLab/GitHub block syntax.
basic.puml
@startuml
title Authentication Sequence
Alice->Bob: Authentication Request
note right of Bob: Bob thinks about it
Bob->Alice: Authentication Response
@enduml
index.md
```plantuml source="basic.puml"
'' This code is appended to the contents of basic.puml
Goofy -> MickeyMouse: calls
Goofy <-- MickeyMouse: responds
```
To use the plugin with Python-Markdown you have these choices:
with pip
, do a simple pip install plantuml-markdown
, and the plugin should be ready to be used
on Windows you can use Chocolatey, a package manager for Windows: do a
choco install plantuml
and you are ready to work (this command will install all dependencies, Java and Graphviz
included, see https://chocolatey.org/packages/plantuml for details)
copy the file plantuml-markdown.py
in the extensions
folder of Python-Markdown. For example, for Python 2.7
you must do:
$ sudo cp plantuml-markdown.py /usr/lib/python27/site-packages/markdown/extensions/
copy the file somewhere in your home. A good choice may be the user-site
path, for example (bash
syntax):
$ export INSTALLPATH="`python -m site --user-site`/plantuml-markdown"
$ mkdir -p "$INSTALLPATH"
$ cp plantuml-markdown.py "$INSTALLPATH/mdx_plantuml-markdown.py"
$ export PYTHONPATH="$INSTALLPATH"
You must export PYTHONPATH
before running markdown_py
, or you can put the definition in ~/.bashrc
.
After installed, you can use this plugin by activating it in the markdown_py
command. For example:
markdown_py -x plantuml_markdown mydoc.md > out.html
But before to use it, you need to configure which PlantUML binary to use: a local binary, or a remote server.
You need to install PlantUML (see the site for details) and Graphviz 2.26.3 or later.
The plugin expects a program plantuml
in the classpath. If not installed by your package
manager, you can create a shell script and place it somewhere in the classpath. For example,
save the following into /usr/local/bin/plantuml
(supposing PlantUML installed into
/opt/plantuml
):
#!/bin/bash
java $PLANTUML_JAVAOPTS -jar /opt/plantuml/plantuml.jar ${@}
The PLANTUML_JAVAOPTS
variable can be used to set specific Java options, such as memory tuning options,
or to set system variable used by PlantUML, such as then include search path. This would avoid modifications of the
plantuml
script.
For example, with a diagram like:
```plantuml
!include myDefs.puml
A --> B
```
you can do:
export PLANTUML_JAVAOPTS="-Dplantuml.include.path=$HOME/plantuml_defs"
markdown_py -x plantuml_markdown mydoc.md > out.html
The same thing can be done using the environment variable _JAVA_OPTIONS
, which is read by default by the java
executable.
On Windows can be used the following plantuml.bat
(many thanks to henn1001):
@echo off
set mypath=%~dp0
setlocal
set GRAPHVIZ_DOT=%mypath%\Graphviz\bin\dot.exe
java %PLANTUML_JAVAOPTS% -jar %mypath%\plantuml.jar %*
Make sure the plantuml.bat
is on the path.
For Gentoo Linux there is an ebuild at http://gpo.zugaina.org/dev-util/plantuml/RDep: you can download
the ebuild and the files
subfolder or you can add the zugaina
repository with layman
(recommended).
From version 2.0
a PlantUML server can be used for rendering diagrams. This speedups a
lot the diagrams rendering but needs to send the diagram source to a server.
You can download the war and deploy in a servlet container, or you can run it as a docker container.
In either cases you need to specify the URL of the server in a configuration file like:
plantuml_markdown:
server: http://www.plantuml.com/plantuml # PlantUML server, for remote rendering
# other global options
insecure: False # set to True if the server uses self-signed certificates
cachedir: /tmp # set a non-empty value to enable caching
base_dir: . # where to search for diagrams to include
config: # PlantUML config file, relative to base_dir (a PlantUML file included in every diagram)
format: png # default diagram image format
classes: class1,class2 # default diagram classes
encoding: utf-8 # character encoding for external files (default utf-8)
title: UML diagram # default title (tooltip) for diagram images
alt: UML diagram image # default `alt` attribute for diagram images
image_maps: True # generate image maps when the format is png and there are hyperlinks
priority: 30 # plugin priority; the higher, the sooner will be applied (default 30)
http_method: GET # GET or POST - note that plantuml.com only supports GET (default GET)
fallback_to_get: True # When using POST, should GET be used as fallback (POST will fail if @startuml/@enduml tags not used) (default True)
theme: bluegray # theme to be set, can be overridden inside puml files, (default none)
puml_notheme_cmdlist: [
'version',
'listfonts',
'stdlib',
'license'
] # theme will not be set if listed commands present (default as listed)
Then you need to specify the configuration file on the command line:
markdown_py -x plantuml_markdown -c myconfig.yml mydoc.md > out.html
Starting from version 3.7.0
a Kroki server can be used as an alternative of PlantUML server.
The configuration is similar, only use the server_kroki
configuration property instead of the server
property.
Usually, remote servers, for security reasons, do not allow arbitrary '!include' instructions to be executed.
To try to bypass this limitation, the plugin behaves as follows:
!include <C4/C4_Container>
http
or https
, the inclusion can be handled by the server; be aware that
the server may refuse to include them (Kroki in an example)server_include_whitelist
configuration, the file is
assumed to be safe for the server; an example is !include C4/C4_Container.puml
with the server Kroki, which has a
copy of the C4 library internallyinclude
statement is replaced with the contents of the
file before sending it to the remote server. This behavior can be changed by declaring an appropriate regular
expression in server_include_whitelist
or by adding a comment to the line:
local
, include is forced local; e.g. !include C4/C4_Container.puml ' local file
will search and read the local file C4/C4_Container.puml
remote
, include is treated as a server side include;
for example !include my_configuration.puml 'server-side include
If using a local PlantUML installation includes works out of the box only if includes are in the current directory. If they are in other directories there are two possibilities:
!include includes/my-defs.puml
)base_dir
option in the plugin configuration (ex: base_dir: includes
) AND change the default plantuml
command in something like plantuml_cmd: java -Dplantuml.include.path=includes -jar path/to/plantuml.jar
The plugin has several configuration option:
alt
: text to show when image is not available. Defaults to uml diagram
base_dir
: path where to search for external diagrams filescachedir
: directory for caching of diagrams. Defaults to ''
, no cachingclasses
: space separated list of classes for the generated image. Defaults to uml
config
: PlantUML config file, relative to base_dir
(a PlantUML file included before every diagram, see
PlantUML documentation). Defaults to None
encoding
: character encoding for external files (see source
parameter); default encoding is utf-8
. Please note
that on Windows text files may use the cp1252
as default encoding, so setting encoding: cp1252
may fix incorrect
characters rendering.fallback_to_get
: Fallback to GET
if POST
fails. Defaults to Trueformat
: format of image to generate (png
, svg
, svg_object
, svg_inline
or txt
). Defaults to png
(See
example section above for further explanations of the values for format
)remove_inline_svg_size
: When format
is svg_inline
, remove the width
and height
attributes of the generated
SVG. Defaults to True
http_method
: Http Method for server - GET
or POST
. "Defaults to GET
image_maps
: generate image maps if format is png
and the diagram has hyperlinks; true
, on
, yes
or 1
activates image maps, everything else disables it. Defaults to True
insecure
: if True
do not validate SSL certificate of the PlantUML server; set to True
when using a custom
PlantUML installation with self-signed certificates. Defaults to False
kroki_server
: Kroki server url, as alternative to server
for remote rendering (image maps mus be disabled
manually). Defaults to ''
, use PlantUML server if definedplantuml_cmd
: command to run for executing PlantUML locally; for example, if you need to set the include directory
the value can be java -Dplantuml.include.path=includes -jar plantuml.jar
. Defaults to plantuml
(the system script)priority
: extension priority. Higher values means the extension is applied sooner than others. Defaults to 30
puml_notheme_cmdlist
: theme will not be set if listed commands present. Default list is
['version', 'listfonts', 'stdlib', 'license']
. If modifying please copy the default list provided and appendserver
: PlantUML server url, for remote rendering. Defaults to ''
, use local commandserver_include_whitelist
: List of regular expressions defining which include files are supported by the server.
Defaults to [r'^c4.*$']
(all files starting with c4
). See Inclusion Management for
detailstheme
: Default Theme to use, will be overridden by !theme directive. Defaults to blank i.e. Plantuml none
themetitle
: tooltip for the diagramFor passing options to the plantuml_plugin
see the documentation of the tool you are using.
For markdown_py
, simply write a YAML file with the configurations and use the -c
option on the command line.
See the Using a PlantUML server section for an example.
priority
configurationWith markdownm_py
plugin extensions can conflict if they manipulate the same block of text.
Examples are the Fenced Code Blocks
or Snippets extensions.
Every plugin has a priority configured, most wants to be run as te first or the last plugin in the chain. The
plantuml_markdown
plugin fits in the middle, trying to work as best without conflicting with other plugins.
If you are getting strange behaviours in conjunction with other plugins, you can use the priority
configuration to
try to avoid the conflict, letting the plugin run before (higher value) or after other plugins (lower value).
As an example of possible conflicts see issue #38.
plantuml-markdown
is tested with Python >= 3.6 and Markdown >= 3.0.1
. Older versions of Python or Markdown
may
work, but if it doesn't I can't guarantee a fix as they are end-of-life versions.
The test execution requires a specific version of PlantUML (the image generated can be different with different PlantUML versions).
Before to run tests, install the required dependencies:
pip install -r test-requirements.txt
To run the tests, execute the following command:
nose2 --verbose -F
This command uses a custom version of the plantuml
command which will download the expected version of PlantUML for
tests execution without clobbering the system.
This requires docker
and docker-compose
to be installed
First setup a small python alpine image with all the dependencies pre-installed.
docker-compose build
then run the container to automatically trigger tests and print the output mapping the contents of your workspace
docker-compose up
To set specific version of Markdown or Python:
PTYHON_VER=3.9 MARKDOWN_VER=3.3.7 docker-compose build && docker-compose up