PlantUML Markdown Extension

Warnings

• deprecated The `server` and `kroki_server` configuration options are deprecated starting from version 3.11.0.
  Fix: Use the new `servers` option, which accepts a list of server URLs, allowing for a pool of servers for remote rendering. For example: `servers: ['http://www.plantuml.com/plantuml', 'https://kroki.io/plantuml']`.
• gotcha When using local PlantUML binary rendering, `plantuml-markdown` requires Java and Graphviz to be installed and the `plantuml` command to be available in your system's PATH. Without these, local rendering will fail.
  Fix: Ensure Java is installed, download `plantuml.jar`, and create a wrapper script (e.g., `/usr/local/bin/plantuml`) that executes `java -jar /path/to/plantuml.jar`. Also, install Graphviz and make sure the `plantuml` command is discoverable in your system's PATH.
• gotcha Prior to version 3.9.8, inline SVG output might have included an erroneous `ns0:` prefix on SVG tags, potentially causing rendering issues in some viewers.
  Fix: Upgrade to `plantuml-markdown` version 3.9.8 or later to resolve the `ns0:` prefix issue.
• gotcha Include directives (`!include`) in PlantUML diagrams, especially when used with multiple `base_dir` paths, were subject to bugs in versions 3.10.0 through 3.10.4 regarding how included files were located.
  Fix: Ensure you are using `plantuml-markdown` version 3.10.5 or later for improved reliability when using `base_dir` with multiple paths or `!include` directives. Refer to the documentation for correct `base_dir` configuration.
• gotcha Version 3.11.0 contained a minor f-string formatting error that primarily affected Python versions older than 3.12, potentially leading to runtime issues.
  Fix: Upgrade to `plantuml-markdown` version 3.11.1 or later if you are running Python environments older than 3.12.

Install

• pip install plantuml-markdown Install `plantuml-markdown`

Imports

• plantuml_markdown

  import markdown
  
  md = markdown.Markdown(extensions=['plantuml_markdown'], extension_configs={'plantuml_markdown': {'servers': ['http://www.plantuml.com/plantuml']}})

  The library is primarily used as a Python-Markdown extension, loaded via the `extensions` and `extension_configs` parameters of `markdown.Markdown`.

Quickstart

This quickstart demonstrates how to convert Markdown text containing PlantUML diagrams into HTML using `plantuml-markdown`. It shows both the GitHub-style triple-backtick syntax and the `::uml::` block syntax. The example configures a remote PlantUML server via the `servers` option, which is the recommended approach for versions 3.11.0 and later. For MkDocs, the plugin is enabled and configured in `mkdocs.yml`.

import markdown
import os

# For local rendering, ensure 'plantuml' command is in PATH and Java/Graphviz are installed.
# For remote rendering, use a server.
# This example uses a remote server for simplicity.
# In a real application, consider using os.environ for sensitive URLs or more robust configuration.
plantuml_server = os.environ.get('PLANTUML_SERVER_URL', 'http://www.plantuml.com/plantuml')

markdown_text = """
# My Document with a PlantUML Diagram

Here's a simple sequence diagram:

```plantuml format="svg"
Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response
Alice -> Bob: Another action
```

And another one, using the alternative ::uml:: syntax:

::uml:: format="png"
Goofy -> MickeyMouse: calls
Goofy <-- MickeyMouse: responds
::end-uml::
"""

md = markdown.Markdown(extensions=['plantuml_markdown'], extension_configs={
    'plantuml_markdown': {
        'servers': [plantuml_server], # Using the new 'servers' config, introduced in 3.11.0
        'cachedir': 'plantuml_cache' # Optional: enable caching
    }
})

html_output = md.convert(markdown_text)
print(html_output)

# Example for MkDocs (mkdocs.yml)
# plugins:
#   - plantuml_markdown:
#       servers:
#         - http://www.plantuml.com/plantuml
#       cachedir: plantuml_cache