# MkDocs-Build-Plantuml-Plugin
## Table of Contents
- [About the Project](#about-the-project)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Usage](#usage)
- [Dark Mode Support](#dark-mode-support)
- [Known restrictions](#known-restrictions)
- [Contributing](#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
````markdown
```plantuml
Alice -> Bob
```
````
this plugin does _not_ meet your requirements. Please check out [plantuml-markdown](https://github.com/mikitex70/plantuml-markdown) which does exactly that.
## Prerequisites
You need to have installed:
- Python3 (>= 3.12)
- [MkDocs](https://www.mkdocs.org)
- Java for Plantuml (If running locally)
- [Plantuml](https://plantuml.com) (if running locally)
- This plugin (needs [httplib2](https://pypi.org/project/httplib2/) for server rendering)
On macOS you can install plantuml with homebrew which puts a plantuml executable in `/usr/local/bin/plantuml`.
## Installation
```shell
pip3 install mkdocs-build-plantuml-plugin
```
## Usage
### Plugin Settings
In `mkdocs.yml` add this plugin section (depicted are the default values):
```yaml
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:
```python
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:
```markdown
# My MkDocs Document
## Example Plantuml Images
```
## 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
1. Grab a general (ie. for [Material Theme](https://squidfunk.github.io/mkdocs-material/)) dark mode support css file (i.e. from [henrywhitaker3/mkdocs-material-dark-theme](https://github.com/henrywhitaker3/mkdocs-material-dark-theme)) for your theme
1. Enable theme support in this plugin:
- build_plantuml:
[...]
theme_enabled: true
theme_folder: "include/themes"
theme_light: "light.puml"
theme_dark: "dark.puml"
1. You have to provide two puml theme files, ie mydarkmode.puml and mylightmode.puml
1. In the out directory a `<file>.<ext>` will be created and additionally a `<file>_dark.<ext>`
1. Insert your images in markdown with `` (this selector is then used in the [JS file](example/docs/javascript/images_dark.js) to know which images have to be exchanged)
1. provide [`extra_javascript`](./example/docs/javascript/images_dark.js) file which handles the switch
You can find an example in the [example folder](./example/)
### Example Output
## Known restrictions
- If you use `!include` and the `render: "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.
Raw data
{
"_id": null,
"home_page": "https://github.com/christo-ph/mkdocs_build_plantuml",
"name": "mkdocs-build-plantuml-plugin",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "mkdocs plantuml publishing documentation uml sequence diagram",
"author": "Christoph Galler",
"author_email": "galler@quantor.consulting",
"download_url": "https://files.pythonhosted.org/packages/a8/f8/e00b685ad5390a617a2e5325ebd14103fdfbd35c3d8a74810752f306d086/mkdocs-build-plantuml-plugin-1.11.0.tar.gz",
"platform": null,
"description": "\n\n# MkDocs-Build-Plantuml-Plugin\n\n## Table of Contents\n\n- [About the Project](#about-the-project)\n- [Prerequisites](#prerequisites)\n- [Installation](#installation)\n- [Usage](#usage)\n- [Dark Mode Support](#dark-mode-support)\n- [Known restrictions](#known-restrictions)\n- [Contributing](#contributing)\n\n## About the Project\n\nThis plugin automates the generation of PlantUML image files when using `mkdocs serve`.\n\nThe 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.\n\n**Note**: If you want inline diagrams in your Markdown files\n\n````markdown\n```plantuml\nAlice -> Bob\n```\n````\n\nthis plugin does _not_ meet your requirements. Please check out [plantuml-markdown](https://github.com/mikitex70/plantuml-markdown) which does exactly that.\n\n## Prerequisites\n\nYou need to have installed:\n\n- Python3 (>= 3.12)\n- [MkDocs](https://www.mkdocs.org)\n- Java for Plantuml (If running locally)\n- [Plantuml](https://plantuml.com) (if running locally)\n- This plugin (needs [httplib2](https://pypi.org/project/httplib2/) for server rendering)\n\nOn macOS you can install plantuml with homebrew which puts a plantuml executable in `/usr/local/bin/plantuml`.\n\n## Installation\n\n```shell\npip3 install mkdocs-build-plantuml-plugin\n```\n\n## Usage\n\n### Plugin Settings\n\nIn `mkdocs.yml` add this plugin section (depicted are the default values):\n\n```yaml\nplugins:\n - search\n - build_plantuml:\n render: 'server' # or \"local\" for local rendering\n bin_path: '/usr/local/bin/plantuml' # ignored when render: server\n server: 'http://www.plantuml.com/plantuml' # official plantuml server\n disable_ssl_certificate_validation: true # for self-signed and invalid certs\n output_format: 'svg' # or \"png\"\n allow_multiple_roots: false # in case your codebase contains more locations for diagrams (all ending in diagram_root)\n diagram_root: 'docs/diagrams' # should reside under docs_dir\n output_folder: 'out'\n input_folder: 'src'\n input_extensions: '' # comma separated list of extensions to parse, by default every file is parsed\n```\n\nIt is recommended to use the `server` option, which is much faster than `local`.\n\n### Example folder structure\n\nThis would result in this directory layout:\n\n```python\ndocs/ # the default MkDocs docs_dir directory\n diagrams/\n include/ # for include files like theme.puml etc (optional, won't be generated)\n out/ # the generated images, which can be included in your md files\n subdir1/file1.svg # you can organise your diagrams in subfolders, see below\n file.svg\n src/ # the Plantuml sources\n subdir1/file1.puml\n subdir2/\n file.puml\nmkdocs.yml # mkdocs configuration file\n\n```\n\nWhen starting with `mkdocs serve`, it will create all diagrams initially.\n\nAfterwards, 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\u2018t take long until the site reloads and does not get into a loop.\n\n### Including generated images\n\nInside your `index.md` or any other Markdown file you can then reference any created image as usual:\n\n```markdown\n# My MkDocs Document\n\n## Example Plantuml Images\n\n\n\n\n```\n\n## Dark Mode Support\n\nSince Version 1.4 this plugin can support dark mode when rendering with `server` (prefers-color-scheme).\n\n**Note**: Not in local mode, only server rendering mode\n\n1. Grab a general (ie. for [Material Theme](https://squidfunk.github.io/mkdocs-material/)) dark mode support css file (i.e. from [henrywhitaker3/mkdocs-material-dark-theme](https://github.com/henrywhitaker3/mkdocs-material-dark-theme)) for your theme\n1. Enable theme support in this plugin:\n\n - build_plantuml:\n [...]\n theme_enabled: true\n theme_folder: \"include/themes\"\n theme_light: \"light.puml\"\n theme_dark: \"dark.puml\"\n\n1. You have to provide two puml theme files, ie mydarkmode.puml and mylightmode.puml\n1. In the out directory a `<file>.<ext>` will be created and additionally a `<file>_dark.<ext>`\n1. Insert your images in markdown with `` (this selector is then used in the [JS file](example/docs/javascript/images_dark.js) to know which images have to be exchanged)\n1. provide [`extra_javascript`](./example/docs/javascript/images_dark.js) file which handles the switch\n\nYou can find an example in the [example folder](./example/)\n\n### Example Output\n\n\n\n## Known restrictions\n\n- If you use `!include` and the `render: \"server\"` option, this plugin merges those files manually. If there are any issues or side effects because of that, please open a ticket.\n- Dark mode / theme support is currently only available in server rendering mode.\n\n## Contributing\n\nContributions are welcome! If you find any issues or have suggestions for improvements, please open an issue or submit a pull request.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "An MkDocs plugin to call plantuml locally or remote",
"version": "1.11.0",
"project_urls": {
"Homepage": "https://github.com/christo-ph/mkdocs_build_plantuml"
},
"split_keywords": [
"mkdocs",
"plantuml",
"publishing",
"documentation",
"uml",
"sequence",
"diagram"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "23c34e670e59e5edf8c4c136bee1604dd149e2b4c393b4266cdb10c7a93aefac",
"md5": "47c0f7146cda9aac94d4a6b318792c81",
"sha256": "528e883a7e5485576b60a51e22dc0232d31e5ae7c19640f9dc201f655e9ce0f5"
},
"downloads": -1,
"filename": "mkdocs_build_plantuml_plugin-1.11.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "47c0f7146cda9aac94d4a6b318792c81",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 9318,
"upload_time": "2024-03-25T13:36:32",
"upload_time_iso_8601": "2024-03-25T13:36:32.702150Z",
"url": "https://files.pythonhosted.org/packages/23/c3/4e670e59e5edf8c4c136bee1604dd149e2b4c393b4266cdb10c7a93aefac/mkdocs_build_plantuml_plugin-1.11.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a8f8e00b685ad5390a617a2e5325ebd14103fdfbd35c3d8a74810752f306d086",
"md5": "8a218c5e8afa9f2d6c6f758884f4dfb0",
"sha256": "3e894ab71e75f37f8c5236dbe4e63d938312bfa7a5fc2489cf9347a659db41f8"
},
"downloads": -1,
"filename": "mkdocs-build-plantuml-plugin-1.11.0.tar.gz",
"has_sig": false,
"md5_digest": "8a218c5e8afa9f2d6c6f758884f4dfb0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 8933,
"upload_time": "2024-03-25T13:36:34",
"upload_time_iso_8601": "2024-03-25T13:36:34.376795Z",
"url": "https://files.pythonhosted.org/packages/a8/f8/e00b685ad5390a617a2e5325ebd14103fdfbd35c3d8a74810752f306d086/mkdocs-build-plantuml-plugin-1.11.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-25 13:36:34",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "christo-ph",
"github_project": "mkdocs_build_plantuml",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "mkdocs-build-plantuml-plugin"
}
JSON
