{"id":4171,"library":"plantuml-markdown","title":"PlantUML Markdown Extension","description":"plantuml-markdown is a Python-Markdown extension that enables embedding PlantUML diagrams directly into Markdown documents. It supports local PlantUML binary rendering, remote PlantUML servers, and Kroki servers. The current version is 3.11.1, with a regular release cadence addressing bug fixes and new features.","status":"active","version":"3.11.1","language":"en","source_language":"en","source_url":"https://github.com/mikitex70/plantuml-markdown","tags":["markdown","plantuml","diagrams","mkdocs","documentation","uml"],"install":[{"cmd":"pip install plantuml-markdown","lang":"bash","label":"Install `plantuml-markdown`"}],"dependencies":[{"reason":"This is a Markdown extension and requires the Python-Markdown library to function.","package":"Markdown","optional":false},{"reason":"Required if using local PlantUML binary for rendering diagrams.","package":"Java","optional":true},{"reason":"Required if using local PlantUML binary for rendering diagrams, as PlantUML relies on Graphviz for layout.","package":"Graphviz","optional":true}],"imports":[{"note":"The library is primarily used as a Python-Markdown extension, loaded via the `extensions` and `extension_configs` parameters of `markdown.Markdown`.","symbol":"plantuml_markdown","correct":"import markdown\n\nmd = markdown.Markdown(extensions=['plantuml_markdown'], extension_configs={'plantuml_markdown': {'servers': ['http://www.plantuml.com/plantuml']}})"}],"quickstart":{"code":"import markdown\nimport os\n\n# For local rendering, ensure 'plantuml' command is in PATH and Java/Graphviz are installed.\n# For remote rendering, use a server.\n# This example uses a remote server for simplicity.\n# In a real application, consider using os.environ for sensitive URLs or more robust configuration.\nplantuml_server = os.environ.get('PLANTUML_SERVER_URL', 'http://www.plantuml.com/plantuml')\n\nmarkdown_text = \"\"\"\n# My Document with a PlantUML Diagram\n\nHere's a simple sequence diagram:\n\n```plantuml format=\"svg\"\nAlice -> Bob: Authentication Request\nBob --> Alice: Authentication Response\nAlice -> Bob: Another action\n```\n\nAnd another one, using the alternative ::uml:: syntax:\n\n::uml:: format=\"png\"\nGoofy -> MickeyMouse: calls\nGoofy <-- MickeyMouse: responds\n::end-uml::\n\"\"\"\n\nmd = markdown.Markdown(extensions=['plantuml_markdown'], extension_configs={\n    'plantuml_markdown': {\n        'servers': [plantuml_server], # Using the new 'servers' config, introduced in 3.11.0\n        'cachedir': 'plantuml_cache' # Optional: enable caching\n    }\n})\n\nhtml_output = md.convert(markdown_text)\nprint(html_output)\n\n# Example for MkDocs (mkdocs.yml)\n# plugins:\n#   - plantuml_markdown:\n#       servers:\n#         - http://www.plantuml.com/plantuml\n#       cachedir: plantuml_cache","lang":"python","description":"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`."},"warnings":[{"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']`.","message":"The `server` and `kroki_server` configuration options are deprecated starting from version 3.11.0.","severity":"deprecated","affected_versions":">= 3.11.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade to `plantuml-markdown` version 3.9.8 or later to resolve the `ns0:` prefix issue.","message":"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.","severity":"gotcha","affected_versions":"< 3.9.8"},{"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.","message":"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.","severity":"gotcha","affected_versions":"3.10.0 - 3.10.4"},{"fix":"Upgrade to `plantuml-markdown` version 3.11.1 or later if you are running Python environments older than 3.12.","message":"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.","severity":"gotcha","affected_versions":"3.11.0 (on Python < 3.12)"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}