Rust by Example: the book you compile, not just read

What Rust by Example is, and who it is written for

Rust by Example is a book made of small Rust programs. Each chapter introduces a language feature and shows it running, rather than describing it in prose and leaving the reader to write the first line. The README states the scope plainly: "Learn Rust with examples (Live code editor included)". The live editor is part of the hosted version at doc.rust-lang.org, not something you get from a local build.

The audience is narrow in a useful way. It assumes you have decided to learn Rust and want to start typing it. It does not assume prior systems programming, and it does not try to be a tour of the standard library. If you have never programmed before, the pace will feel abrupt; this is a book of demonstrations, not a course with scaffolding. If you already know another compiled language, the density is the appeal: you can read a chapter, change two lines, and see what the compiler says.

How the book is assembled: mdbook, Handlebars templates and po files

The repository is not a static site. It is an mdbook project. The top level holds book.toml, the src/ directory with the chapter sources, a theme/ directory for presentation, and a po/ directory for translations. The primary language reported for the repository is Handlebars, which matches the theme and templating layer rather than the content, since the content itself is Markdown with Rust snippets.

That layout explains the workflow. You edit files under src/, mdbook renders them into a book, and translations live beside the original text as gettext catalogs in po/. The README shows the language being selected at build time through an environment variable, MDBOOK_BOOK__LANGUAGE, which mdbook reads as an override for the book configuration. One consequence is that a translation is a build-time choice, not a runtime toggle; you produce a separate build per language.

The README also warns that a preprocessor named mdbook-gettext may be missing and that the warning about it is safe to ignore. That warning is worth understanding rather than dismissing: gettext handling is optional in this setup, so a build can succeed while translation plumbing is inactive.

Installing mdbook and building Rust by Example on your machine

The README gives a four-step local path. First install Rust from the official toolchain page, then clone, then install mdbook with cargo, then build and serve. The commands below are copied from the README's Using section.

git clone https://github.com/rust-lang/rust-by-example
cd rust-by-example
cargo install mdbook
mdbook build
mdbook serve

mdbook build writes the rendered book into the output directory configured in book.toml; mdbook serve starts a local web server and rebuilds when files change. The README does not state the port, so read it from the server output rather than assuming one.

For a translated build, the README sets the language through the environment variable. The example uses Japanese:

MDBOOK_BOOK__LANGUAGE=ja mdbook build
MDBOOK_BOOK__LANGUAGE=ja mdbook serve

One constraint is stated directly in the README: running the examples requires an internet connection. Reading does not. If you work offline, expect the embedded editor to be unavailable while the text itself still renders. The README does not document rollback or how to pin a specific mdbook version, so a build that breaks after a cargo update has no documented recovery path beyond installing a different version yourself.

The offline reading claim versus the runnable editor

The README draws a line that is easy to miss on a first read: you can read all content offline, but running examples needs a connection. These are two different products sharing one interface. The prose and code listings are static Markdown rendered by mdbook. The live code editor is a remote component.

This matters for anyone planning to use the book on a plane, in a locked-down network, or inside a CI container. A local mdbook build gives you a readable book and nothing more. The repository does not ship a local Rust execution service, and the README does not describe one. If your goal is a self-contained sandbox where snippets execute, Rust by Example is the wrong layer; you would be building that yourself.

There is a second, subtler limitation. Snippets in a teaching book are small by design. They demonstrate one idea each, which means they rarely show error handling, module boundaries or ownership patterns interacting at realistic scale. That is a deliberate trade-off, not an oversight, but it means the book cannot be your only source for how a real crate is structured.

Rust by Example compared with Rustlings and the official book

The search results around this project are dominated by comparisons, and the comparisons are legitimate because the tools occupy different positions.

The official Rust book is explanatory. It builds concepts in sequence with prose as the primary carrier and code as illustration. Rust by Example inverts that ratio: code is primary, prose is a caption. If you retain syntax better by reading it than by reading about it, the inversion is the whole point.

Rustlings is a different mechanism again. It is an exercise set: you clone it, run a command, and fix failing files until the tests pass. Rust by Example has no grading loop. You are not told whether your understanding is correct; you are shown working code and expected to notice the difference when you break it. That is a real weakness for self-directed learners who need feedback to stay oriented, and it is the strongest argument for using both.

Translations are the other axis. The README lists community translations for Bulgarian, French, Russian, Vietnamese and Portuguese, hosted in separate repositories rather than inside this one. Those are external projects with their own maintenance, which is worth knowing before you rely on one.

Contributing, licensing and the cost of keeping a book current

The repository is not archived, and the last push was on 2026-09-15, which is recent. That matters for a teaching text tied to a language that changes on a six-week release train.

Licensing is dual. The README states the project is licensed under either Apache License 2.0 or the MIT license, at your option, and that contributions intentionally submitted for inclusion are dually licensed on the same terms unless you state otherwise. For most readers this is uninteresting. For anyone planning to fork the content into internal training material, the practical effect is that you must carry the licence terms and, under Apache-2.0, the notice requirements; MIT is the more permissive of the two options. That is a description of the terms, not legal advice, and the LICENSE-APACHE and LICENSE-MIT files are the authoritative text.

The upgrade cost is the part people underestimate. Because translations are gettext catalogs in po/, an edit to an English chapter can invalidate the corresponding translated strings, and the README's translation guides (TRANSLATING.md, TRANSLATING_JA.md, TRANSLATING_ZH.md) exist precisely because that coordination is work. A contributor changing a paragraph is not changing one file; they are potentially touching the source of every language build.

Editorial conclusion

Adopt Rust by Example if you learn by editing working code and you want a reference you can grep inside your own checkout. Do not adopt it as your only resource if you need graded exercises with pass or fail feedback; that is Rustlings' job, and the two are complementary rather than interchangeable. Before you commit to a workflow, verify two things in your own clone: that mdbook build completes on the toolchain you have installed, and that the language you want actually exists as a .po file under po/, because the README only names Japanese and Chinese translation guides.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. Project website
4. README
5. rust-lang/rust-by-example on GitHub