plantuml-markdown

What it is and what it does

This package extends Python-Markdown to recognize PlantUML diagram blocks and render them as images. You write diagram syntax in a Markdown code block using a special `::uml::` or ` ```plantuml ` delimiter, and the plugin converts it to an embedded PNG, SVG, or text representation in the final HTML. It supports both local PlantUML binaries (requiring Java and Graphviz) and remote rendering via PlantUML or Kroki servers, with options for image dimensions, CSS classes, alt text, and external file inclusion.

The plugin is a pure-Python wheel with no runtime dependencies, making it lightweight to install. Configuration is optional but recommended—you specify which rendering backend to use (local or remote), caching preferences, default image format, and other metadata. It integrates directly into the markdown_py command-line tool or Python-Markdown API.

Use it for:

• Generate architecture and sequence diagrams automatically from Markdown documentation without manual image creation.
• Embed UML diagrams in technical specifications or design documents that are version-controlled as plain text.
• Render diagrams in static site generators (Jekyll, Hugo, Sphinx) that use Markdown as input.
• Create interactive SVG diagrams with navigable links in HTML output when using svg_object or svg_inline formats.
• Include external PlantUML files in Markdown via the source parameter for modular diagram management.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

A Markdown extension that converts PlantUML diagram syntax into rendered images (PNG, SVG, or text) embedded in HTML documents, using either a local PlantUML binary or a remote server.

Yes, if you use Markdown for documentation and want to embed UML diagrams without manual image creation. Install is frictionless and the package is actively maintained. Requires either a local PlantUML setup (Java + Graphviz) or network access to a remote server—factor that into your workflow before committing. No security issues reported.

Install

plantuml-markdown on PyPI

pip install plantuml-markdown

uv add plantuml-markdown

poetry add plantuml-markdown

Installing plantuml-markdown

Before you install

Low friction: pure Python wheel with no runtime dependencies. Active maintenance—last commit 2026-04-18, 226 repository stars. Requires external PlantUML binary or remote server access to function; not a standalone tool.

License in practice

Permissive license (BSD). No restrictions on commercial or private use; safe to include in proprietary projects.

Quickstart

pip install plantuml-markdown

markdown_py -x plantuml_markdown mydoc.md > out.html

In mydoc.md:
::uml:: format="png"
  Alice -> Bob: Hello
  Bob --> Alice: Hi
::end-uml::

Requires PlantUML binary installed locally (with Java and Graphviz) or a configured remote PlantUML/Kroki server URL; Markdown processing requires Python-Markdown.

Verify before relying

• Whether the package works with current Python-Markdown versions and any version constraints beyond 'requires_python >= 3.0'.
• Performance characteristics when rendering large diagrams or many diagrams in a single document.
• Whether caching (mentioned in config) actually improves rendering speed in typical workflows.

Package facts

Evidence: plantuml_markdown-3.11.2-py3-none-any.whl

Keywords: Markdown, typesetting, include, plugin, extension

Tags

More Python Modules packages