CLI helper for managing PlantUML diagram sources and their previews in Markdown files [](https://github.com/grissius/plantaznik/actions/workflows/test.yaml?query=branch%3Amaster++) [](https://crates.io/crates/plantaznik)

Motivation

PlantUML is a great tool for managing software spec diagrams. Unless you are on GitLab, which has built-in support for interpreting PlantUML diagram sources you need to get hacky and inconvenient and even more so for private repos.

Plantaznik is a tool you can integrate into your workflow, that does the menial job for you: find referenced PlantUML sources, generate links and update in the Markdown docs.

Getting started

Installation

sh $ cargo install plantaznik

Alternatively download a precompiled version from releases.

How to use

In your Markdown files, include the following declarations in the comment: html <!-- plantaznik:./path/to/plantuml/source.plantuml --> (this line will be replaced)

The declarations include a path to the source file, which is relative to the current file.

sh $ plantaznik README.md All targeted input files (assume utf8 encoded markdown files with \n lines) are processed and the lines following the declerations are replaced by a Markdown syntax image, pointing to official PlantUML server with your source code encoded in the link.

Example of verbose output: sh $ plantaznik README.md -vvv [DEBUG] Replacement README.md:4 [DEBUG] - ![]() [DEBUG] + ![](https://www.plantuml.com/plantuml/svg/SyfFKj2rKt3CoKnELR1Io4ZDoSa70000) [DEBUG] Replacement README.md:42 (no change) [WARN ] Replacement README.md:93: Error accessing file: Read ./missing-diagram.plantuml (caused by: No such file or directory (os error 2)) [INFO ] File README.md processed (2/3 successful replacements)

Advanced usage

• Use globbing to target more files $ plantaznik '**/*.md'
• Increase verbosity with repeated v swtich $ plantaznik README.md -vvvv. Error (default), Warning, Info, Trace
• Declarations Markdown codeblocks are automatically skipped

TODO

• [ ] Add check mode + status codes
• [ ] Add switch for output (svg/png) (or preserve mode)
• [ ] Add img alts (or preserve mode)
• [ ] Bail option

Alternatives

• puml-for-markdown - Lot of features, including the url shortening. I had troubles running it myself for some reason. The advantage of plantaznik are in my opinion speed, simplicity, better file filtering (glob support) and relative path handing (not always towards to root, but relative to file).
• Workaround for public repos on GitHub
• GitLab support
• Mermaid on GitHub