Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Rendering at docs build time

No diagram in this book is a checked-in image. Authors write a fenced code block, and a preprocessor replaces it with inline SVG while the book builds. This page shows how to write such a block and how to build the book, for contributors and for anyone who wants the same setup in their own mdBook.

From chapter to page «input» Chapter Markdown mdBook Book Loader HTML Renderer mdbook-drumlin drumlin crate «output» Published Site IPreprocess IRender hook inline SVG

How to write one

Use a code fence with the language drumlin:

```drumlin
component Client { requires IGreeting }
component Server { provides IGreeting }
```

The page then shows the source and this diagram:

Client Server IGreeting

Fence options

FenceOutput
```drumlinSource, then diagram
```drumlin,render-onlyDiagram alone
```drumlin,errorSource, then drumlin’s real error message

Set up

The preprocessor is a small Rust program that links drumlin as a library.

# book.toml
[preprocessor.drumlin]
command = "mdbook-drumlin"
cargo install --path docs/mdbook-drumlin --locked
mdbook build docs

Why render during the build

  • Examples cannot go stale. Each image always comes from the source beside it.
  • A broken diagram breaks the build. A parse error stops mdbook build. So does a drumlin,error example that parses successfully.
  • Error messages stay honest. The Errors page shows output captured at build time.
  • Pages need no client-side rendering. Readers get plain SVG with no JavaScript.
  • The result is static. The built book is plain HTML and SVG, which any web server can serve. The repository’s Dockerfile builds it.