Security News
Research
Data Theft Repackaged: A Case Study in Malicious Wrapper Packages on npm
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
mkdocs-build-plantuml-plugin
Advanced tools
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.
You need to have installed:
On macOS you can install plantuml with homebrew which puts a plantuml executable in /usr/local/bin/plantuml
.
pip3 install mkdocs-build-plantuml-plugin
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
.
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.
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)
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
!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.Contributions are welcome! If you find any issues or have suggestions for improvements, please open an issue or submit a pull request.
FAQs
An MkDocs plugin to call plantuml locally or remote
We found that mkdocs-build-plantuml-plugin demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.
Security News
The Ultralytics' PyPI Package was compromised four times in one weekend through GitHub Actions cache poisoning and failure to rotate previously compromised API tokens.