Command line

mdbook-swirly                      run as a preprocessor (mdBook does this)
mdbook-swirly install [DIR]        add the preprocessor to a book
mdbook-swirly render [FILE]        render one specification to stdout
mdbook-swirly supports <RENDERER>  preprocessor protocol handshake
mdbook-swirly --help
mdbook-swirly --version

No arguments — preprocess

Reads the mdBook preprocessor payload ([context, book] as JSON) on stdin and writes the modified book on stdout. mdBook invokes this; you would not normally run it yourself, and it reports as much if you do.

Exits non-zero if a diagram fails to render, unless on-error = "warn".

supports <renderer>

Exits 0 for every renderer. mdBook asks this before each build.

Answering anything but a clean exit 0 makes mdBook skip the preprocessor without reporting anything, so this arm is deliberately incapable of failing — it returns before reading configuration, starting the engine, or touching stdin.

install [DIR]

Writes assets/swirly.css and adds the [preprocessor.swirly] and additional-css entries to book.toml. DIR defaults to the current directory and must contain a book.toml.

Additive and idempotent. Comments, key order and existing additional-css entries are preserved; the previous book.toml is kept as book.toml.bak. A command you have already set is left alone, so pointing it at a local build survives a re-run.

render [FILE]

Renders one specification to SVG on stdout. Reads stdin if FILE is omitted.

mdbook-swirly render diagram.txt > diagram.svg
mdbook-swirly render --theme sodium diagram.txt
echo '@ t | 0 | 1' | mdbook-swirly render

The SVG carries class="swirly", so dropping it into a page that has swirly.css loaded gives the same theme-following behaviour as inside a book. Without that stylesheet an adaptive rendering inherits whatever color is in effect where you put it.

Environment

Set to anything other than empty or 0. It is an environment variable rather than a flag because mdBook owns the invocation, so this way one build can be debugged without editing book.toml:

MDBOOK_SWIRLY_DEBUG=1 mdbook build

The stack is hidden by default because the bundled renderer is minified: the trace is a single offset into one very long line, which tells a reader nothing and makes an ordinary message — a slot count, an unknown theme — look like a crash. It is still the only view into the bundle when something there genuinely breaks.

Exit codes