mdbook-swirly
An mdBook preprocessor that renders Swirly diagrams to SVG while your book builds.
Write a diagram in a fenced block tagged swirly:
```swirly
@ t | 0 | 1 | 2 | 3 | 4 | 5
= c | 'a' | | 'b' | | 'c' |
to = 5
> s1 | | 'b' | | 'c' | |
```
and the page gets this in its place:
No client-side JavaScript, no image files to keep in step with the prose, and nothing fetched when the page loads. The diagram above is an SVG that was rendered when this page was built — and it follows your theme, so try the paint roller in the toolbar.
What Swirly draws
Swirly has two diagram species:
- Marble diagrams — the familiar timeline of events flowing through an operator, from the RxJS tradition.
- Grid diagrams — rows sharing one discrete, labelled transaction axis, mixing event streams with held-value cells. These are the diagrams the Functional Reactive Programming book uses, and the reason this fork exists.
Both are written as plain text you can diff, review and edit in place.
Where to start
This documentation follows Diátaxis, which sorts documentation by what you are trying to do:
| Tutorial | Never used it? Start here and build a book with a diagram in it. |
| How-to guides | You know what you want; these are the recipes. |
| Reference | Every syntax form, configuration key and command. |
| Explanation | Why it works the way it does. |
| Examples | Every example in the Swirly repository, rendered. |
Install
cargo install mdbook-swirly
cd my-book
mdbook-swirly install
The tutorial walks through that from an empty directory.