Package: plantuml-markdown
PlantUMLExtension forPython-MarkdownIntroductionInstallationUsing a local plantUML binaryUsing a remote serverUsing a PlantUML serverUsing a Kroki serverFile inclusion managementPlugin optionsA note on thepriorityconfigurationRunning testsRunning tests using DockerIntroductionThis plugin implements a block extension that can be used to specify aPlantUMLdiagram 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 orderid,format,classes,alt,title,width,height, andsource.
The option value may be enclosed in single or double quotes.Supported values forformatparameter are:png: HTMLimgtag with embedded png imagesvg: HTMLimgtag with embedded svg image (links are not navigable)svg_object: HTMLobjecttag with embedded svg image (links are navigable)svg_inline: HTML5svgtag with inline svg image source (links are navigable, can be manipulated with CSS rules)txt: plain text diagrams.Thewidthandheightoptions must include aCSS unit.sourceparameter 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
@endumlindex.md```plantuml source="basic.puml"
'' This code is appended to the contents of basic.puml
Goofy ->  MickeyMouse: calls
Goofy <-- MickeyMouse: responds
```InstallationTo use the plugin withPython-Markdownyou have the following options.  Please note that before using the package, you will need to configure whichPlantUMLbinary to use: a local binary, or a remote server (see below for further details).[Linux] Use Python'spippackage manager and run the following command.  After running, the package should be ready to use.$pipinstallplantuml-markdown[Windows] You can useChocolatey, a package manager for Windows.
From an elevated terminal, run the following command:>>> choco install plantuml(Note: This command will install all dependencies, Java and Graphviz included, seehttps://chocolatey.org/packages/plantumlfor details.)Copy the file./plantuml-markdown.pyinto theextensionsfolder ofPython-Markdown. For example, for Python 2.7, you must do:$sudocpplantuml-markdown.py/usr/lib/python27/site-packages/markdown/extensions/Copy the file somewhere in your home. A good choice may be theuser-sitepath.  For example, on Linux usingbash:$exportINSTALLPATH="`python -m site --user-site`/plantuml-markdown"$mkdir-p"$INSTALLPATH"$cpplantuml-markdown.py"$INSTALLPATH/mdx_plantuml-markdown.py"$exportPYTHONPATH="${PYTHONPATH}:${INSTALLPATH}"You must exportPYTHONPATHbefore runningmarkdown_py, or you can put the definition in a bash config file (eg -~/.bashrc), then restart the terminal or usesource ~/.bashrcor. ~/.bashrcto update the variable without closing the terminal.After the package is installed, you can use this plugin by activating it in themarkdown_pycommand. For example:$markdown_py-xplantuml_markdownmydoc.md>out.htmlUsing a local PlantUML binaryYou need to installPlantUML(see the site for details) andGraphviz2.26.3 or later.
The plugin expects a programplantumlin 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(supposingPlantUMLinstalled into/opt/plantuml):#!/bin/bash
java $PLANTUML_JAVAOPTS -jar /opt/plantuml/plantuml.jar ${@}ThePLANTUML_JAVAOPTSvariable 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 theplantumlscript.
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.htmlThe same thing can be done using the environment variable_JAVA_OPTIONS, which is read by default by thejavaexecutable.On Windows can be used the followingplantuml.bat(many thanks tohenn1001):@echo off
set mypath=%~dp0

setlocal
set GRAPHVIZ_DOT=%mypath%\Graphviz\bin\dot.exe

java %PLANTUML_JAVAOPTS% -jar %mypath%\plantuml.jar %*Make sure theplantuml.batis on the path.ForGentoo Linuxthere is an ebuild athttp://gpo.zugaina.org/dev-util/plantuml/RDep: you can download
the ebuild and thefilessubfolder or you can add thezugainarepository withlayman(recommended).Using a remote serverUsing a PlantUML serverFrom version2.0aPlantUML servercan 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 thewarand deploy in a servlet
container, or you can run it as adocker 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 optionsinsecure:False# set to True if the server uses self-signed certificatescachedir:/tmp# set a non-empty value to enable cachingbase_dir:.# where to search for diagrams to includeconfig:# PlantUML config file, relative to base_dir (a PlantUML file included in every diagram)format:png# default diagram image formatclasses:class1,class2# default diagram classesencoding:utf-8# character encoding for external files (default utf-8)title:UML diagram# default title (tooltip) for diagram imagesalt:UML diagram image# default `alt` attribute for diagram imagesimage_maps:True# generate image maps when the format is png and there are hyperlinkspriority: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.htmlUsing a Kroki serverStarting from version3.7.0aKrokiserver can be used as an alternative ofPlantUML server.
The configuration is similar, only use theserver_krokiconfiguration property instead of theserverproperty.File inclusion managementUsually, 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:the inclusion ofstdliblibraries is considered secure and managed by the server;
example!include <C4/C4_Container>if the source to be included starts withhttporhttps, the inclusion can be handled by the server; be aware that
the server may refuse to include them (Krokiin an example)if the source name matches one of the regular expressions in theserver_include_whitelistconfiguration, the file is
assumed to be safe for the server; an example is!include C4/C4_Container.pumlwith the serverKroki, which has a
copy of the C4 library internallyotherwise, it is assumed that the file is local and that theincludestatement 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 inserver_include_whitelistor by adding a comment to the line:if the comment begins withlocal, include is forced local; e.g.!include C4/C4_Container.puml ' local filewill search and read the local fileC4/C4_Container.pumlif the comment begins withremote, include is treated as a server side include;
for example!include my_configuration.puml 'server-side includeincludes are resolved recursively, as when used with a local PlantUML.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:use the directory in includes (ex:!include includes/my-defs.puml)set thebase_diroption in the plugin configuration (ex:base_dir: includes)ANDchange the default plantuml
command in something likeplantuml_cmd: java -Dplantuml.include.path=includes -jar path/to/plantuml.jarPlugin optionsThe plugin has several configuration option:alt: text to show when image is not available. Defaults touml diagrambase_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 toumlconfig: PlantUML config file, relative tobase_dir(a PlantUML file included before every diagram, seePlantUML documentation). Defaults toNoneencoding: character encoding for external files (seesourceparameter); default encoding isutf-8. Please note
that on Windows text files may use thecp1252as default encoding, so settingencoding: cp1252may fix incorrect
characters rendering.fallback_to_get: Fallback toGETifPOSTfails. Defaults to Trueformat: format of image to generate (png,svg,svg_object,svg_inlineortxt). Defaults topng(See
example section above for further explanations of the values forformat)remove_inline_svg_size: Whenformatissvg_inline, remove thewidthandheightattributes of the generated
SVG. Defaults toTruehttp_method: Http Method for server -GETorPOST. "Defaults toGETimage_maps: generate image maps if format ispngand the diagram has hyperlinks;true,on,yesor1activates image maps, everything else disables it. Defaults toTrueinsecure: ifTruedo not validate SSL certificate of the PlantUML server; set toTruewhen using a custom
PlantUML installation with self-signed certificates. Defaults toFalsekroki_server: Kroki server url, as alternative toserverfor 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 bejava -Dplantuml.include.path=includes -jar plantuml.jar. Defaults toplantuml(the system script)priority: extension priority. Higher values means the extension is applied sooner than others. Defaults to30puml_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 withc4).SeeInclusion Managementfor
detailstheme: Default Theme to use, will be overridden  by !theme directive. Defaults to blank i.e. Plantumlnonethemetitle: tooltip for the diagramFor passing options to theplantuml_pluginsee the documentation of the tool you are using.Formarkdown_py, simply write a YAML file with the configurations and use the-coption on the command line.
See theUsing a PlantUML serversection for an example.A note on thepriorityconfigurationWithmarkdownm_pyplugin extensions can conflict if they manipulate the same block of text.
Examples are theFenced Code BlocksorSnippetsextensions.Every plugin has a priority configured, most wants to be run as te first or the last plugin in the chain. Theplantuml_markdownplugin 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 thepriorityconfiguration 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.Running testsplantuml-markdownis tested with Python >= 3.6 andMarkdown >= 3.0.1. Older versions of Python orMarkdownmay
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 ofPlantUML(the image generated can be different with differentPlantUMLversions).Before to run tests, install the required dependencies:pipinstall-rtest-requirements.txtTo run the tests, execute the following command:nose2--verbose-FThis command uses a custom version of theplantumlcommand which will download the expected version ofPlantUMLfor
tests execution without clobbering the system.Running tests using DockerThis requiresdockeranddocker-composeto be installedFirst setup a small python alpine image with all the dependencies pre-installed.docker-composebuildthen run the container to automatically trigger tests and print the output mapping the contents of your workspacedocker-composeupTo set specific version of Markdown or Python:PTYHON_VER=3.9MARKDOWN_VER=3.3.7docker-composebuild&&docker-composeup