ααLoop docs
On this page

Render DOT figures with Clinnet

Clinnet is Linnet’s command-line companion for documentation and diagram workflows. The Cargo package is named clinnet, while the installed executable is named linnet. It recursively finds DOT files, renders one PDF per graph through Typst, and assembles those PDFs into a grid. Use the Rust library for graph algorithms; use Clinnet when the input is already DOT and the desired result is a browsable set of figures.

Install and render a directory

Clinnet requires Typst 0.15.0 or newer. Install both commands, then confirm the executable’s current flags rather than relying on an older pre-subcommand invocation:

cargo install clinnet
cargo install typst-cli --version 0.15.0 --locked
linnet --help
linnet draw examples

The final command scans examples/ recursively. With default paths it creates:

  • build/figs/, mirroring the input directory and containing one PDF per DOT file;
  • build/grid.pdf, the combined document;
  • build/templates/, containing the default figure, grid, layout, Linnest, and Kurvst assets;
  • build/.cache/figures.json, the per-figure content cache; and
  • build/.cache/run-metadata.json, the plan used by targeted redraw commands.
What a second run reuses
A figure is reused only when its DOT source, selected figure template, explicit --style files, --input values, and the bundled .typ/.wasm assets in build/templates/ have the same content hash. Clinnet does not recursively discover arbitrary imports beside a custom template; pass those files with --style when they must invalidate the cache. The grid is still regenerated from the current figure index. Removing a DOT file removes its stale figure output during the next full draw; deleting the figure cache forces every remaining figure to rebuild.

Customize templates and inputs

Use --figure-template for each individual figure and --grid-template for the combined PDF. Repeat --style for extra files whose contents must invalidate the figure cache. Repeat --input key=value to expose strings through Typst’s sys.inputs in both compilation stages:

linnet --build-dir build draw graphs \
  --figure-template templates/figure.typ \
  --grid-template templates/grid.typ \
  --style templates/colors.typ \
  --input theme=dark \
  --input scale=1.5 \
  --output-path build/review.pdf

Clinnet supplies data-path, data_path, and a derived title to the figure template in addition to caller inputs. --output-path selects the final grid PDF; it is not a figure-template input. Input values are strings; parse them in Typst when a number or boolean is required. The embedded defaults include the canonical Linnest and Kurvst package trees, so a custom template can use the same graph-layout and curve primitives. Continue to the Linnest Typst API for graph construction, layout, inspection, and drawing rather than copying its wrapper surface into a Clinnet template guide.

Templates must share a Typst project root
Clinnet chooses the narrowest existing directory that contains the template and its inputs. A Typst import outside that tree, a missing style file, or a template moved without its dependencies fails before a PDF is produced. Keep the templates and imported assets beneath one project directory and read the full Typst error printed by Clinnet.

Make a targeted rebuild

Run a complete draw once so that the build metadata records the input root, templates, output paths, styles, and figures. You can then rebuild one known DOT figure without rescanning the directory, or rebuild only the grid:

linnet --build-dir build redraw-figure graphs/box.dot --input theme=light
linnet --build-dir build redraw-grid --output-path build/review.pdf

redraw-figure starts with the inputs recorded by the full draw and applies new inputs as per-key overrides. redraw-grid reuses the cached figure list; if any --input is supplied to that command, the supplied list replaces the grid’s recorded input list, so repeat every value the grid template still needs. A target not present in the preceding plan must be added with a new full draw.

Use --no-parallel for deterministic sequential diagnosis, or --jobs N to bound parallel figure compilation. These options affect scheduling, not cache identity or graph semantics.

Source and release boundaries

The implementation and exact Clap definitions are in the Clinnet command source. Clinnet has its own package version and version history, independent of the Rust linnet library. Record the Clinnet and Typst versions when reporting a rendering or cache problem.