qpr - Quick PlantUML Renderer

qpr is a lightweight Bash, Dash or Zsh script that renders PlantUML diagrams using the official Docker image. It simplifies the process of generating SVG or PNG diagrams from the terminal without requiring a local Java or PlantUML installation. Diagrams can also be displayed directly in graphics-capable terminals (currently supporting Kitty).

(Demo video)

Features

• POSIX Compliant: Compatible with bash, dash, and zsh.
• Docker-powered: No local dependencies other than Docker. The script will prompt to pull the plantuml/plantuml image if it's not found locally.
• SVG & PNG Support: Default output is SVG, with an option for PNG.
• Batch Rendering: Supports multiple files or filename prefixes.
• Terminal Preview: Integration with Kitty terminal (kitten icat) to display diagrams directly in your terminal.
• Smart Path Handling: Automatically resolves relative paths for Docker volume mounting.

Templates

The repository includes a templates/ directory with starter files that you can copy and modify for testing the qpr workflow:

• C4 Diagram: Templates for System Context, Container, Component, and Code diagrams using the C4-PlantUML library.
• Class Diagram
• Activity Diagram

Prerequisites

• Docker
• (Optional) Kitty Terminal for the --print feature.

Installation

1. Download the qpr script.
2. Make it executable:

   chmod +x qpr

3. Move it to a directory in your PATH (e.g., ~/.local/bin or /usr/local/bin).

Usage

qpr accepts both full filenames and filename prefixes. If a prefix is provided, it will render all matching .puml files.

qpr [options] <prefix-or-filename>...

Options

• --png Output PNG instead of the default SVG.
• --print Display the resulting PNG in the terminal (requires Kitty terminal). Implies the --png flag.
• -q, --quiet Suppress status messages.
• -h, --help Show help message.

Examples

Render a specific .puml file to SVG:

qpr diagram.puml

Render all .puml files starting with the prefix "c4" to PNG and preview them in the terminal:

qpr --print c4