[](https://travis-ci.org/mikitex70/plantuml-markdown)
[PlantUML][] Extension for [Python-Markdown][]
==============================================
* [Introduction](#introduction)
* [Installation](#installation)
* [Using a local PlantUML binary](#using-a-local-plantuml-binary)
* [Using a remote server](#using-a-remote-server)
* [Using a PlantUML server](#using-a-plantuml-server)
* [Using a Kroki server](#using-a-kroki-server)
* [File inclusion management](#file-inclusion-management)
* [Plugin options](#plugin-options)
* [A note on the `priority` configuration](#a-note-on-the-priority-configuration)
* [Running tests](#running-tests)
* [Running tests using Docker](#running-tests-using-docker)
Introduction
------------
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:
```markdown
::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:
```markdown
::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 image
* `svg`: 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](https://www.w3schools.com/cssref/css_units.asp).
`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
```
Installation
------------
To use the plugin with [Python-Markdown][] you have the following options. Please note that before using the package, you will need to configure which [PlantUML] binary to use: a local binary, or a remote server (see below for further details).
1. [Linux] Use Python's `pip` package manager and run the following command. After running, the package should be ready to use.
```console
$ pip install plantuml-markdown
```
1. [Windows] You can use [Chocolatey](https://chocolatey.org/), a package manager for Windows.
From an elevated terminal, run the following command:
```console
>>> choco install plantuml
```
(__Note__: This command will install all dependencies, Java and Graphviz included, see [https://chocolatey.org/packages/plantuml](https://chocolatey.org/packages/plantuml) for details.)
After the package is installed, you can use this plugin by activating it in the `markdown_py` command. For example:
```console
$ markdown_py -x plantuml_markdown mydoc.md > out.html
```
### Using a local PlantUML binary
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](https://github.com/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.
**IMPORTANT NOTE**: the whole output of the script `plantuml` (or `plantuml.bat` in Windows) is captured and saved as
image, so be sure no other output is done by the script, even blank lines. For example, the first line of the
`plantuml.bat` script **MUST** be `@echo off`.
For [Gentoo Linux][Gentoo] 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).
### Using a remote server
#### Using a PlantUML server
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](http://sourceforge.net/projects/plantuml/files/plantuml.war/download) and deploy in a servlet
container, or you can run it as a [docker container](https://hub.docker.com/r/plantuml/plantuml-server/).
In either cases you need to specify the URL of the server in a configuration file like:
```yaml
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 (can be a list)
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
#### Using a Kroki server
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 `kroki_server` configuration property instead of the `server` property.
#### File inclusion management
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:
* the inclusion of [stdlib](https://plantuml.com/stdlib) libraries is considered secure and managed by the server;
example `!include <C4/C4_Container>`
* if the source to be included starts with `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)
* if the source name matches one of the regular expressions in the `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 internally
* otherwise, it is assumed that the file is local and that the `include` 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:
* if the comment begins with `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`
* if the comment begins with `remote`, include is treated as a server side include;
for example `!include my_configuration.puml 'server-side include`
* includes 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 the `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`
Plugin options
--------------
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 files. Defaults to `.`, can be a list of paths
* `cachedir`: directory for caching of diagrams. Defaults to `''`, no caching
* `classes`: 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](https://plantuml.com/command-line)). 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 True
* `format`: 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 defined
* `plantuml_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 append**
* `server`: PlantUML server url, for remote rendering. Defaults to `''`, use local command
* `server_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](#inclusion-management) for
details**
* `theme`: Default Theme to use, will be overridden by !theme directive. Defaults to blank i.e. Plantuml `none` theme
* `title`: tooltip for the diagram
For 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](#using-plantuml-server) section for an example.
### A note on the `priority` configuration
With `markdownm_py` plugin extensions can conflict if they manipulate the same block of text.
Examples are the [Fenced Code Blocks](https://python-markdown.github.io/extensions/fenced_code_blocks)
or [Snippets](https://facelessuser.github.io/pymdown-extensions/extensions/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](https://github.com/mikitex70/plantuml-markdown/issues/38).
Running tests
-------------
`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:
```bash
pip install -r test-requirements.txt
```
To run the tests, execute the following command:
```bash
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.
Running tests using Docker
-------------------------
This requires `docker` and `docker-compose` to be installed
First setup a small python alpine image with all the dependencies pre-installed.
```bash
docker-compose build
```
then run the container to automatically trigger tests and print the output mapping the contents of your workspace
```bash
docker-compose up
```
To set specific version of Markdown or Python:
```bash
PTYHON_VER=3.9 MARKDOWN_VER=3.3.7 docker-compose build && docker-compose up
```
[Python-Markdown]: https://python-markdown.github.io/
[PlantUML]: http://plantuml.sourceforge.net/
[PlantUML server]: http://plantuml.com/server
[Kroki]: https://kroki.io/
[Graphviz]: http://www.graphviz.org
[Gentoo]: http://www.gentoo.org
[layman]: http://wiki.gentoo.org/wiki/Layman
Raw data
{
"_id": null,
"home_page": "https://github.com/mikitex70/plantuml-markdown",
"name": "plantuml-markdown",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "Markdown, typesetting, include, plugin, extension",
"author": "Michele Tessaro",
"author_email": "michele.tessaro.tex@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/75/2a/806d807ae4f65149b2f132e73b02beb6aa3cd9afc4bd79f45f13dee454b8/plantuml_markdown-3.10.4.tar.gz",
"platform": null,
"description": "[](https://travis-ci.org/mikitex70/plantuml-markdown)\n\n[PlantUML][] Extension for [Python-Markdown][]\n==============================================\n\n* [Introduction](#introduction)\n* [Installation](#installation)\n * [Using a local PlantUML binary](#using-a-local-plantuml-binary)\n * [Using a remote server](#using-a-remote-server)\n * [Using a PlantUML server](#using-a-plantuml-server)\n * [Using a Kroki server](#using-a-kroki-server)\n * [File inclusion management](#file-inclusion-management)\n* [Plugin options](#plugin-options)\n * [A note on the `priority` configuration](#a-note-on-the-priority-configuration)\n* [Running tests](#running-tests)\n* [Running tests using Docker](#running-tests-using-docker)\n\nIntroduction\n------------\n\nThis plugin implements a block extension that can be used to specify a [PlantUML] diagram that will be converted into an\nimage and inserted into the document.\n\nSyntax:\n\n```markdown\n::uml:: [format=\"png|svg|txt\"] [classes=\"class1 class2 ...\"] [alt=\"text for alt\"] [title=\"Text for title\"] [width=\"300px\"] [height=\"300px\"]\n PlantUML script diagram\n::end-uml::\n```\n\nExample:\n\n```markdown\n::uml:: format=\"png\" classes=\"uml myDiagram\" alt=\"My super diagram placeholder\" title=\"My super diagram\" width=\"300px\" height=\"300px\"\n Goofy -> MickeyMouse: calls\n Goofy <-- MickeyMouse: responds\n::end-uml::\n```\n\nThe GitLab/GitHub block syntax is also recognized. Example:\n\n ```plantuml id=\"myDiag\" format=\"png\" classes=\"uml myDiagram\" alt=\"My super diagram placeholder\" title=\"My super diagram\" width=\"300px\" height=\"300px\"\n Goofy -> MickeyMouse: calls\n Goofy <-- MickeyMouse: responds\n ```\n\nOptions are optional (otherwise the wouldn't be options), but if present must be specified in the order \n`id`, `format`, `classes`, `alt`, `title`, `width`, `height`, and `source`.\nThe option value may be enclosed in single or double quotes.\n\nSupported values for `format` parameter are:\n\n* `png`: HTML `img` tag with embedded png image\n* `svg`: HTML `img` tag with embedded svg image (links are not navigable)\n* `svg_object`: HTML `object` tag with embedded svg image (links are navigable)\n* `svg_inline`: HTML5 `svg` tag with inline svg image source (links are navigable, can be manipulated with CSS rules)\n* `txt`: plain text diagrams.\n\nThe `width` and `height` options must include a [CSS unit](https://www.w3schools.com/cssref/css_units.asp).\n\n`source` parameter is used for inclusion of an external source diagram instead on an inline code. Here's an example in\nGitLab/GitHub block syntax.\n\n> basic.puml\n\n @startuml\n title Authentication Sequence\n Alice->Bob: Authentication Request\n note right of Bob: Bob thinks about it\n Bob->Alice: Authentication Response\n @enduml\n\n> index.md\n\n ```plantuml source=\"basic.puml\"\n '' This code is appended to the contents of basic.puml\n Goofy -> MickeyMouse: calls\n Goofy <-- MickeyMouse: responds\n ```\n\nInstallation\n------------\n\nTo use the plugin with [Python-Markdown][] you have the following options. Please note that before using the package, you will need to configure which [PlantUML] binary to use: a local binary, or a remote server (see below for further details).\n\n1. [Linux] Use Python's `pip` package manager and run the following command. After running, the package should be ready to use.\n ```console\n $ pip install plantuml-markdown\n ```\n1. [Windows] You can use [Chocolatey](https://chocolatey.org/), a package manager for Windows.\n From an elevated terminal, run the following command:\n ```console\n >>> choco install plantuml\n ```\n (__Note__: This command will install all dependencies, Java and Graphviz included, see [https://chocolatey.org/packages/plantuml](https://chocolatey.org/packages/plantuml) for details.)\n\n\nAfter the package is installed, you can use this plugin by activating it in the `markdown_py` command. For example:\n ```console\n $ markdown_py -x plantuml_markdown mydoc.md > out.html\n ```\n\n### Using a local PlantUML binary\n\nYou need to install [PlantUML][] (see the site for details) and [Graphviz][] 2.26.3 or later.\nThe plugin expects a program `plantuml` in the classpath. If not installed by your package\nmanager, you can create a shell script and place it somewhere in the classpath. For example,\nsave the following into `/usr/local/bin/plantuml` (supposing [PlantUML][] installed into\n`/opt/plantuml`):\n\n```\n#!/bin/bash\njava $PLANTUML_JAVAOPTS -jar /opt/plantuml/plantuml.jar ${@}\n```\n\nThe `PLANTUML_JAVAOPTS` variable can be used to set specific Java options, such as memory tuning options,\nor to set system variable used by PlantUML, such as then include search path. This would avoid modifications of the\n`plantuml` script. \nFor example, with a diagram like:\n\n````\n```plantuml\n!include myDefs.puml\n\nA --> B\n```\n````\n\nyou can do:\n\n```\nexport PLANTUML_JAVAOPTS=\"-Dplantuml.include.path=$HOME/plantuml_defs\"\nmarkdown_py -x plantuml_markdown mydoc.md > out.html\n```\n\nThe same thing can be done using the environment variable `_JAVA_OPTIONS`, which is read by default by the `java`\nexecutable.\n\nOn Windows can be used the following `plantuml.bat` (many thanks to [henn1001](https://github.com/henn1001)):\n\n```\n@echo off\nset mypath=%~dp0\n\nsetlocal\nset GRAPHVIZ_DOT=%mypath%\\Graphviz\\bin\\dot.exe\n\njava %PLANTUML_JAVAOPTS% -jar %mypath%\\plantuml.jar %*\n```\n\nMake sure the `plantuml.bat` is on the path.\n\n**IMPORTANT NOTE**: the whole output of the script `plantuml` (or `plantuml.bat` in Windows) is captured and saved as \nimage, so be sure no other output is done by the script, even blank lines. For example, the first line of the \n`plantuml.bat` script **MUST** be `@echo off`.\n\nFor [Gentoo Linux][Gentoo] there is an ebuild at http://gpo.zugaina.org/dev-util/plantuml/RDep: you can download\nthe ebuild and the `files` subfolder or you can add the `zugaina` repository with [layman][]\n(recommended).\n\n### Using a remote server\n\n#### Using a PlantUML server\n\nFrom version `2.0` a [PlantUML server] can be used for rendering diagrams. This speedups a\nlot the diagrams rendering but needs to send the diagram source to a server.\n\nYou can download the [war](http://sourceforge.net/projects/plantuml/files/plantuml.war/download) and deploy in a servlet\ncontainer, or you can run it as a [docker container](https://hub.docker.com/r/plantuml/plantuml-server/).\n\nIn either cases you need to specify the URL of the server in a configuration file like:\n\n```yaml\nplantuml_markdown:\n server: http://www.plantuml.com/plantuml # PlantUML server, for remote rendering\n # other global options\n insecure: False # set to True if the server uses self-signed certificates\n cachedir: /tmp # set a non-empty value to enable caching\n base_dir: . # where to search for diagrams to include (can be a list)\n config: # PlantUML config file, relative to base_dir (a PlantUML file included in every diagram)\n format: png # default diagram image format\n classes: class1,class2 # default diagram classes\n encoding: utf-8 # character encoding for external files (default utf-8)\n title: UML diagram # default title (tooltip) for diagram images\n alt: UML diagram image # default `alt` attribute for diagram images\n image_maps: True # generate image maps when the format is png and there are hyperlinks\n priority: 30 # plugin priority; the higher, the sooner will be applied (default 30)\n http_method: GET # GET or POST - note that plantuml.com only supports GET (default GET) \n fallback_to_get: True # When using POST, should GET be used as fallback (POST will fail if @startuml/@enduml tags not used) (default True)\n theme: bluegray # theme to be set, can be overridden inside puml files, (default none)\n puml_notheme_cmdlist: [ \n 'version', \n 'listfonts', \n 'stdlib', \n 'license'\n ] # theme will not be set if listed commands present (default as listed)\n```\n\nThen you need to specify the configuration file on the command line:\n\n markdown_py -x plantuml_markdown -c myconfig.yml mydoc.md > out.html\n\n#### Using a Kroki server\n\nStarting from version `3.7.0` a [Kroki] server can be used as an alternative of [PlantUML server].\nThe configuration is similar, only use the `kroki_server` configuration property instead of the `server` property.\n\n#### File inclusion management\n\nUsually, remote servers, for security reasons, do not allow arbitrary '!include' instructions to be executed.\n\nTo try to bypass this limitation, the plugin behaves as follows:\n* the inclusion of [stdlib](https://plantuml.com/stdlib) libraries is considered secure and managed by the server; \n example `!include <C4/C4_Container>`\n* if the source to be included starts with `http` or `https`, the inclusion can be handled by the server; be aware that \n the server may refuse to include them ([Kroki] in an example)\n* if the source name matches one of the regular expressions in the `server_include_whitelist` configuration, the file is\n assumed to be safe for the server; an example is `!include C4/C4_Container.puml` with the server [Kroki], which has a\n copy of the C4 library internally\n* otherwise, it is assumed that the file is local and that the `include` statement is replaced with the contents of the \n file before sending it to the remote server. This behavior can be changed by declaring an appropriate regular\n expression in `server_include_whitelist` or by adding a comment to the line:\n * if the comment begins with `local`, include is forced local; e.g. `!include C4/C4_Container.puml ' local file`\n will search and read the local file `C4/C4_Container.puml`\n * if the comment begins with `remote`, include is treated as a server side include;\n for example `!include my_configuration.puml 'server-side include`\n* includes are resolved recursively, as when used with a local PlantUML.\n\nIf using a local PlantUML installation includes works out of the box only if includes are in the current directory. If \nthey are in other directories there are two possibilities:\n* use the directory in includes (ex: `!include includes/my-defs.puml`)\n* set the `base_dir` option in the plugin configuration (ex: `base_dir: includes`) **AND** change the default plantuml\n command in something like `plantuml_cmd: java -Dplantuml.include.path=includes -jar path/to/plantuml.jar` \n\nPlugin options\n--------------\n\nThe plugin has several configuration option:\n\n* `alt`: text to show when image is not available. Defaults to `uml diagram`\n* `base_dir`: path where to search for external diagrams files. Defaults to `.`, can be a list of paths\n* `cachedir`: directory for caching of diagrams. Defaults to `''`, no caching\n* `classes`: space separated list of classes for the generated image. Defaults to `uml`\n* `config`: PlantUML config file, relative to `base_dir` (a PlantUML file included before every diagram, see\n [PlantUML documentation](https://plantuml.com/command-line)). Defaults to `None`\n* `encoding`: character encoding for external files (see `source` parameter); default encoding is `utf-8`. Please note \n that on Windows text files may use the `cp1252` as default encoding, so setting `encoding: cp1252` may fix incorrect \n characters rendering.\n* `fallback_to_get`: Fallback to `GET` if `POST` fails. Defaults to True\n* `format`: format of image to generate (`png`, `svg`, `svg_object`, `svg_inline` or `txt`). Defaults to `png` (See \n example section above for further explanations of the values for `format`)\n* `remove_inline_svg_size`: When `format` is `svg_inline`, remove the `width` and `height` attributes of the generated\n SVG. Defaults to `True`\n* `http_method`: Http Method for server - `GET` or `POST`. \"Defaults to `GET`\n* `image_maps`: generate image maps if format is `png` and the diagram has hyperlinks; `true`, `on`, `yes` or `1`\n activates image maps, everything else disables it. Defaults to `True`\n* `insecure`: if `True` do not validate SSL certificate of the PlantUML server; set to `True` when using a custom \n PlantUML installation with self-signed certificates. Defaults to `False`\n* `kroki_server`: Kroki server url, as alternative to `server` for remote rendering (image maps mus be disabled \n manually). Defaults to `''`, use PlantUML server if defined\n* `plantuml_cmd`: command to run for executing PlantUML locally; for example, if you need to set the include directory\n the value can be `java -Dplantuml.include.path=includes -jar plantuml.jar`. Defaults to `plantuml` (the system script)\n* `priority`: extension priority. Higher values means the extension is applied sooner than others. Defaults to `30`\n* `puml_notheme_cmdlist`: theme will not be set if listed commands present. Default list is\n `['version', 'listfonts', 'stdlib', 'license']`. **If modifying please copy the default list provided and append**\n* `server`: PlantUML server url, for remote rendering. Defaults to `''`, use local command\n* `server_include_whitelist`: List of regular expressions defining which include files are supported by the server. \n Defaults to `[r'^c4.*$']` (all files starting with `c4`). **See [Inclusion Management](#inclusion-management) for \n details**\n* `theme`: Default Theme to use, will be overridden by !theme directive. Defaults to blank i.e. Plantuml `none` theme\n* `title`: tooltip for the diagram\n\nFor passing options to the `plantuml_plugin` see the documentation of the tool you are using.\n\nFor `markdown_py`, simply write a YAML file with the configurations and use the `-c` option on the command line.\nSee the [Using a PlantUML server](#using-plantuml-server) section for an example.\n\n### A note on the `priority` configuration\n\nWith `markdownm_py` plugin extensions can conflict if they manipulate the same block of text. \nExamples are the [Fenced Code Blocks](https://python-markdown.github.io/extensions/fenced_code_blocks)\nor [Snippets](https://facelessuser.github.io/pymdown-extensions/extensions/snippets/) extensions.\n\nEvery plugin has a priority configured, most wants to be run as te first or the last plugin in the chain. The\n`plantuml_markdown` plugin fits in the middle, trying to work as best without conflicting with other plugins.\n\nIf you are getting strange behaviours in conjunction with other plugins, you can use the `priority` configuration to\ntry to avoid the conflict, letting the plugin run before (higher value) or after other plugins (lower value).\n\nAs an example of possible conflicts see issue [#38](https://github.com/mikitex70/plantuml-markdown/issues/38).\n\n\nRunning tests\n-------------\n\n`plantuml-markdown` is tested with Python >= 3.6 and `Markdown >= 3.0.1`. Older versions of Python or `Markdown` may\nwork, but if it doesn't I can't guarantee a fix as they are end-of-life versions.\n\nThe test execution requires a specific version of [PlantUML] (the image generated can be different with different \n[PlantUML] versions).\n\nBefore to run tests, install the required dependencies:\n\n```bash\npip install -r test-requirements.txt\n```\n\nTo run the tests, execute the following command:\n\n```bash\nnose2 --verbose -F\n```\n\nThis command uses a custom version of the `plantuml` command which will download the expected version of [PlantUML] for\ntests execution without clobbering the system.\n\n\nRunning tests using Docker\n-------------------------\n\nThis requires `docker` and `docker-compose` to be installed\n\nFirst setup a small python alpine image with all the dependencies pre-installed. \n```bash\ndocker-compose build\n``` \n\nthen run the container to automatically trigger tests and print the output mapping the contents of your workspace\n\n```bash\ndocker-compose up\n```\n\nTo set specific version of Markdown or Python:\n```bash\nPTYHON_VER=3.9 MARKDOWN_VER=3.3.7 docker-compose build && docker-compose up\n```\n\n\n[Python-Markdown]: https://python-markdown.github.io/\n[PlantUML]: http://plantuml.sourceforge.net/\n[PlantUML server]: http://plantuml.com/server\n[Kroki]: https://kroki.io/\n[Graphviz]: http://www.graphviz.org\n[Gentoo]: http://www.gentoo.org\n[layman]: http://wiki.gentoo.org/wiki/Layman\n",
"bugtrack_url": null,
"license": null,
"summary": "A PlantUML plugin for Markdown",
"version": "3.10.4",
"project_urls": {
"Homepage": "https://github.com/mikitex70/plantuml-markdown"
},
"split_keywords": [
"markdown",
" typesetting",
" include",
" plugin",
" extension"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "fd1272cdf2f4220c37be55d2c56a093013e4f385f006493ac2942a2a18f82801",
"md5": "30c35b66844e09b65f316ac0b84dccca",
"sha256": "23e66b0ea958fc4335400b961784885138e497b9af7d2870d3cc800b11c22cea"
},
"downloads": -1,
"filename": "plantuml_markdown-3.10.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "30c35b66844e09b65f316ac0b84dccca",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 18868,
"upload_time": "2024-09-12T05:48:33",
"upload_time_iso_8601": "2024-09-12T05:48:33.709382Z",
"url": "https://files.pythonhosted.org/packages/fd/12/72cdf2f4220c37be55d2c56a093013e4f385f006493ac2942a2a18f82801/plantuml_markdown-3.10.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "752a806d807ae4f65149b2f132e73b02beb6aa3cd9afc4bd79f45f13dee454b8",
"md5": "2c73564515b44d759e40115a53412680",
"sha256": "5c303ef498dd6fd8efcfc8fe2540109fb6e3aac5bebaf09e33b6413ab3e5c374"
},
"downloads": -1,
"filename": "plantuml_markdown-3.10.4.tar.gz",
"has_sig": false,
"md5_digest": "2c73564515b44d759e40115a53412680",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 30578,
"upload_time": "2024-09-12T05:48:35",
"upload_time_iso_8601": "2024-09-12T05:48:35.572468Z",
"url": "https://files.pythonhosted.org/packages/75/2a/806d807ae4f65149b2f132e73b02beb6aa3cd9afc4bd79f45f13dee454b8/plantuml_markdown-3.10.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-12 05:48:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mikitex70",
"github_project": "plantuml-markdown",
"travis_ci": true,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "Markdown",
"specs": []
},
{
"name": "requests",
"specs": []
},
{
"name": "six",
"specs": []
}
],
"lcname": "plantuml-markdown"
}
JSON
