A short visual introduction to Rust, with interactive ownership and borrowing diagrams generated by RustViz. The tutorial is built as an mdBook — each chapter embeds RustViz visualizations alongside the prose.
The book is built by the mdbook-rustviz
mdBook preprocessor, which compiles each visualization snippet through
the RustViz compiler plugin and inlines the resulting SVGs into the
rendered HTML.
You'll need:
-
The RustViz CLI, which installs the plugin and its toolchain. The RustViz plugin links against
rustc_private, so it needs one specific nightly (todaynightly-2026-05-01, therust-toolchain.tomlof rustviz/rustviz).rustviz initinstalls that nightly (withrust-src,rustc-devandllvm-tools-preview) and the plugin:cargo install rustviz rustviz init
-
mdBook 0.5+. mdBook 0.5 needs Rust ≥ 1.88, which the project nightly above already provides:
cargo +nightly-2026-05-01 install mdbook --version "^0.5" -
The mdBook preprocessor:
cargo install mdbook-rustviz
Then, in this repo:
RV_RUNNER=local mdbook serve --openRV_RUNNER=local runs the plugin in-process, which is fast and
doesn't need Docker. The default RV_RUNNER=docker runs each
snippet in a sandboxed rustviz/rustviz-runner container — useful
if you're authoring a public site and don't want to trust arbitrary
snippets, but heavier to set up.
To try plugin or preprocessor changes in this book, install from a
checkout of rustviz/rustviz instead
of crates.io. That repo's rust-toolchain.toml picks the nightly, so the
toolchain from rustviz init (or cargo xtask setup) still applies:
git clone https://github.com/rustviz/rustviz
cd rustviz
cargo install --locked --path rustviz-plugin
cargo install --locked --path mdbook-rustvizcargo xtask setup also installs the plugin and the toolchain, but not
mdbook-rustviz, so run the second command either way. After every change
to the plugin or the preprocessor, reinstall (the book runs the installed
binaries, not your source tree) and rebuild here with
RV_RUNNER=local mdbook serve --open. See the "Building from this checkout"
section of the rustviz README
for details.
Code blocks tagged ```rv are picked up by the preprocessor and
turned into a side-by-side code panel + timeline visualization. For
example:
```rv
fn main() {
let s = String::from("hello");
println!("{}", s);
}
```To keep a helper function out of a figure, end its signature line with
// rustviz: hide. The function's definition is dropped from the rendered
code panel, along with its parameters' timelines, while the calls to it in
main are still drawn. The marker only works on fn lines (free functions
and methods); on a struct or use line it is ignored
(rustviz/rustviz#814). When
you hide a function, say in the prose what it does, since readers can no
longer see its body.
The deploy workflow (.github/workflows/deploy.yml) instead builds the
plugin and preprocessor from rustviz/rustviz's main, so the published book
always renders with the latest RustViz. Pushes to master deploy it to
https://rustviz.github.io/tutorial/.
See mdbook-rustviz's README
for configuration options.