#cli #plantuml #readme #encode #links

app plantaznik

CLI helper for managing PlantUML diagram sources and their previews in Markdown files

3 releases

0.1.2 Mar 17, 2023
0.1.1 Mar 17, 2023
0.1.0 Mar 15, 2023

#87 in Encoding

Download history 61/week @ 2023-03-13 3/week @ 2023-03-20

64 downloads per month

MIT license

20KB
396 lines

CLI helper for managing PlantUML diagram sources and their previews in Markdown files


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

$ cargo install plantaznik

Alternatively download a precompiled version from releases.

How to use

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.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:

$ 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

Dependencies

~3–4MB
~91K SLoC