An MkDocs plugin to call plantuml locally or remote
Project description
MkDocs-Build-Plantuml-Plugin
Table of Contents
- About the Project
- Prerequisites
- Installation
- Usage
- Dark Mode Support
- Known restrictions
- Contributing
About the Project
This plugin automates the generation of PlantUML image files when using mkdocs serve
.
The motivation behind this plugin is to provide a solution for users who prefer not to use inline diagrams and have encountered challenges with non-functional !includes.
Note: If you want inline diagrams in your Markdown files
```plantuml
Alice -> Bob
```
this plugin does not meet your requirements. Please check out plantuml-markdown which does exactly that.
Prerequisites
You need to have installed:
- Python3 (>= 3.12)
- MkDocs
- Java for Plantuml (If running locally)
- Plantuml (if running locally)
- This plugin (needs httplib2 for server rendering)
On macOS you can install plantuml with homebrew which puts a plantuml executable in /usr/local/bin/plantuml
.
Installation
pip3 install mkdocs-build-plantuml-plugin
Usage
Plugin Settings
In mkdocs.yml
add this plugin section (depicted are the default values):
plugins:
- search
- build_plantuml:
render: 'server' # or "local" for local rendering
bin_path: '/usr/local/bin/plantuml' # ignored when render: server
server: 'http://www.plantuml.com/plantuml' # official plantuml server
disable_ssl_certificate_validation: true # for self-signed and invalid certs
output_format: 'svg' # or "png"
allow_multiple_roots: false # in case your codebase contains more locations for diagrams (all ending in diagram_root)
diagram_root: 'docs/diagrams' # should reside under docs_dir
output_folder: 'out'
input_folder: 'src'
input_extensions: '' # comma separated list of extensions to parse, by default every file is parsed
It is recommended to use the server
option, which is much faster than local
.
Example folder structure
This would result in this directory layout:
docs/ # the default MkDocs docs_dir directory
diagrams/
include/ # for include files like theme.puml etc (optional, won't be generated)
out/ # the generated images, which can be included in your md files
subdir1/file1.svg # you can organise your diagrams in subfolders, see below
file.svg
src/ # the Plantuml sources
subdir1/file1.puml
subdir2/
file.puml
mkdocs.yml # mkdocs configuration file
When starting with mkdocs serve
, it will create all diagrams initially.
Afterwards, it checks if the *.puml
(or other ending) file has a newer timestamp than the corresponding file in out. If so, it will generate a new image (works also with includes). This way, it won‘t take long until the site reloads and does not get into a loop.
Including generated images
Inside your index.md
or any other Markdown file you can then reference any created image as usual:
# My MkDocs Document
## Example Plantuml Images
![file](diagrams/out/file.svg)
![file1](diagrams/out/subdir1/file1.svg)
Dark Mode Support
Since Version 1.4 this plugin can support dark mode when rendering with server
(prefers-color-scheme).
Note: Not in local mode, only server rendering mode
-
Grab a general (ie. for Material Theme) dark mode support css file (i.e. from henrywhitaker3/mkdocs-material-dark-theme) for your theme
-
Enable theme support in this plugin:
- build_plantuml: [...] theme_enabled: true theme_folder: "include/themes" theme_light: "light.puml" theme_dark: "dark.puml"
-
You have to provide two puml theme files, ie mydarkmode.puml and mylightmode.puml
-
In the out directory a
<file>.<ext>
will be created and additionally a<file>_dark.<ext>
-
Insert your images in markdown with
![file](diagrams/out/file.svg#darkable)
(this selector is then used in the JS file to know which images have to be exchanged) -
provide
extra_javascript
file which handles the switch
You can find an example in the example folder
Example Output
Known restrictions
- If you use
!include
and therender: "server"
option, this plugin merges those files manually. If there are any issues or side effects because of that, please open a ticket. - Dark mode / theme support is currently only available in server rendering mode.
Contributing
Contributions are welcome! If you find any issues or have suggestions for improvements, please open an issue or submit a pull request.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for mkdocs-build-plantuml-plugin-1.11.0.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 3e894ab71e75f37f8c5236dbe4e63d938312bfa7a5fc2489cf9347a659db41f8 |
|
MD5 | 8a218c5e8afa9f2d6c6f758884f4dfb0 |
|
BLAKE2b-256 | a8f8e00b685ad5390a617a2e5325ebd14103fdfbd35c3d8a74810752f306d086 |
Hashes for mkdocs_build_plantuml_plugin-1.11.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 528e883a7e5485576b60a51e22dc0232d31e5ae7c19640f9dc201f655e9ce0f5 |
|
MD5 | 47c0f7146cda9aac94d4a6b318792c81 |
|
BLAKE2b-256 | 23c34e670e59e5edf8c4c136bee1604dd149e2b4c393b4266cdb10c7a93aefac |