CLI helper for managing PlantUML diagram sources and their previews in Markdown files
⚡ Fast | 💪 Powerful file selection | ✅ Check mode for CI | 🎨 Customizable output | 🪝 Ideal for git hooks
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.
$ cargo install plantaznikAlternatively download a precompiled version from releases.
In your Markdown files, include the following declarations in the comment:
<!-- 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.
$ plantaznik README.mdAll 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:
$ plantaznik README.md -vvv
[DEBUG] Replacement README.md:4
[DEBUG] - ![]()
[DEBUG] + 
[DEBUG] Replacement README.md:42 (no change)
[ERROR] 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)CLI helper for managing PlantUML diagram sources and their previews in Markdown files
Usage: plantaznik [OPTIONS] <GLOB>
Arguments:
<GLOB> README files glob pattern to process
Options:
-d, --dry-run Dry run (skips file writes)
-c, --check-only Check (skips file writes and error if updates would take place)
-v, --verbose... More output per occurrence
-q, --quiet... Less output per occurrence
-h, --help Print help
-V, --version Print version
- Use globbing to target more files
$ plantaznik '**/*.md'. The links are resolved relative to the current markdown file. - Increase verbosity with repeated
vswtich$ plantaznik README.md -vvvv. Error (default), Warning, Info, Trace. Mute output with-q --helpto see usage and options
Are you not happy with the default generated links? Run once and modify the generated line to your liking.
If the replacement line already contains a PlantUML link (duck-regex-typed), only the encoded source code will be replaced. Use this to your adventage by customizing the image URL placement, alt text or switching to PNG formats. The given line must not contain links to other diagrams.
When running for the first time, the following code is produced: , here are some examples on how you can change the line and still get the code synchronization:
- change the image to PNG- add alt text- change the server<div><img src="https://www.plantuml.com/plantuml/png/ENCODED_SOURCE"></div>- use custom markup[](https://www.plantuml.com/plantuml/uml/ENCODED_SOURCE)- add hyperlink to edit on public server (uses the link twice)
- Declarations Markdown codeblocks are automatically skipped
You can use the check mode (--check-only) to make sure all diagrams are in sync. Copy the GitHub Actions workflow directly (plantaznik.yaml, change the glob pattern if needed) or use it as an inspiration for your CI.
You can preview example runs on this repo.
Currently, I am happy with the features and functionality, if there is something that you would like to see, feel free to open an issue!
- 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