The Rust Cookbook pins two different mdbook versions and excludes seven recipes from its own workspace
https://rust-lang-nursery.github.io/rust-cookbook
At a glance
- What is it?
- rust-lang-nursery/rust-cookbook serves tested recipes as an mdBook where every recipe is a crate, so cargo test and a spellcheck script guard the prose and the code together. Seven crates sit outside that workspace, and the offline instructions and the Makefile disagree about which mdbook to install.
- Who is it for?
- This cookbook earns its place for anyone who already writes Rust and wants a working pattern for one task, not a language course, because every recipe is compiled and tested rather than pasted. Two caveats belong in the same breath.
- Can I use it commercially?
- Yes. CC0-1.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 10 days ago.
- What is it written in?
- Mainly Rust, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- rust-lang-nursery/rust-cookbook2,630 ★ · +9
| Repository | 2026-10-04 | 2026-11-15 |
|---|---|---|
| rust-lang-nursery/rust-cookbook | 2.6k | 2.6k |
9 Stars in the last 42 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The offline instructions and the Makefile pin different mdbook versions
The page gives two ways to read the book locally and they do not agree on the tool. The offline section installs a specific version and serves the result:
$ git clone https://github.com/rust-lang-nursery/rust-cookbook
$ cd rust-cookbook
$ cargo install mdbook --vers "0.4.43"
$ mdbook serve --openThe Makefile's install target, which the development section tells you to use for local work, installs a different one, 0.5.3, and both the build and serve targets depend on that target running first. So the two documented paths produce a book with two different renderers, and a reader who follows the first block ends up with an mdbook version the project's own build never uses. The generated output is the same shape either way: a `book` subdirectory you can open directly, with the per platform commands given for Linux, Windows and macOS. What differs is the tool that produces it, and nothing on the page explains the discrepancy.
Seven recipes sit outside the workspace that runs the tests
The claim on the page is that the examples are complete, suitable for copying into new cargo projects, tested and guaranteed to work. That guarantee is mechanical: each recipe is a crate in one cargo workspace, and the test target runs the workspace. The workspace manifest also carries an exclude list, and seven paths appear in it. Two are database recipes, one for sea_orm and one for sqlx. One is a multimedia playback crate. Two are web crates built on leptos, a base and a hydrate companion. The last two are a wasm component guest and its host. Those recipes are in the tree and in the book, and they are not compiled by the run that backs the guarantee, which is the gap a reader has to know about before treating every page as verified. The exclusions exist for a reason the manifest does not state: these are the crates whose dependency trees or target requirements do not fit the shared workspace.
Shared dependencies are chosen for the playground, not the recipes
The workspace dependency block lists rand, rand_distr, tracing and tracing-subscriber, and it carries a comment that changes how to read it. Those dependencies add crates to the Rust playground, the browser based runner, and the comment asks readers to be wary of removing or changing them without considering that. It links to the playground's top crates list at a fixed commit hash, so the reasoning is traceable to an exact revision of someone else's configuration. The effect on this project is that a dependency version here can be constrained by what the playground bundles rather than by what a recipe needs, and a cookbook recipe that wants a different major version cannot simply ask for it in the shared block. It is an unusual constraint for a documentation project, and it is the clearest sign that these examples are written to be pasted into a playground as much as into a local project.
The root package is edition 2018 inside an edition 2024 workspace
The manifest declares two edition values. The workspace package block sets edition 2024 with version 1.1.0 and the licence expression MIT OR Apache-2.0, and the root package block below it sets edition 2018 with the same version and the same licence expression. Both also set publish to false, so nothing here is meant to reach a registry as a library. The root package is the cookbook crate itself, with a build script, a source directory and a tests directory, and it is the one member that carries the older edition. Everything else inherits 2024 from the workspace default. Nothing breaks from this, and a reader can ignore it, but it is the kind of leftover that shows up when a workspace default moves forward and one manifest is not updated, and it tells you the root crate is maintained separately from the recipes.
A test run is cargo test followed by a spellcheck
The test target does two different kinds of checking in sequence. It runs cargo test across the workspace, which compiles and exercises every recipe crate that the workspace includes, and then it runs a shell script from the ci directory with the argument list, which spell checks the book's own text. So the same command guards the code and the prose, and a contributor whose recipe is fine can still fail the run over a misspelled word in the surrounding paragraph. Formatting is handled the same way, with a target that runs cargo fmt across the workspace and then a custom task that formats the code blocks inside the markdown, and a check-only variant of both used by the lint target before clippy runs with warnings treated as errors. The book is written as source code about source code, and the tooling treats it that way throughout.
make deploy tests once and then tells the script to skip
The deploy target is a chain worth reading carefully. It depends on clean and on dev, and dev is build followed by test, so the tests do run before anything is published. It then invokes the deployment script with a skip flag, and the script is the same one the page offers as a standalone command with no arguments. The script's own job is described in three steps: build and test the book, push the built site to the gh-pages branch, and let GitHub Pages serve it. So through make, the testing happens once in the make layer and is explicitly turned off in the script layer, which is a sensible division and also a contradiction to anyone reading the three steps as a description of what make deploy alone does. The page notes that the whole path needs maintainer permissions on the gh-pages branch, which is the only place where a fork is genuinely blocked.
CC0 for the prose, MIT or Apache for the crates
The repository carries two licences on purpose, and the split is stated plainly. The prose is under Creative Commons Zero v1.0 Universal, with a LICENSE-CC0 file at the root, and the licence section adds that any contribution intentionally submitted for inclusion is dedicated to the public domain unless the contributor says otherwise. The code side is different: every crate manifest, including the workspace default and the root package, declares MIT OR Apache-2.0. That is the standard Rust pairing, and it is what a reader copying a recipe into a commercial project needs. The dual arrangement matters because a documentation project and a set of code samples have different downstream requirements, and the page resolves them rather than leaving one licence to cover both. The repository's own metadata records the Creative Commons Zero identifier, which is the licence of the text, not of the sample code.
A compiled artifact and two CI systems sit in the root
The top level of the tree mixes build output, automation and instructions in a way worth knowing before anyone files an issue. There is a file named libtest.rmeta, which is a compiled metadata artifact rather than source, checked in next to a build script and a tests directory. There are two continuous integration configurations, a travis file at the root and an appveyor configuration beside it, alongside a github directory. There is a theme directory, so the book carries a custom mdbook theme rather than the default, and an assets directory that the build target copies into the output after the renderer runs. There is also a CLAUDE.md file, a deployment document, a contributing guide and a scripts directory. None of that is a problem on its own. Together it describes a book that is generated, tested, spell checked, formatted and deployed by a Makefile whose help target exists so a new contributor can list the commands without reading the file.
Editorial conclusion
This cookbook earns its place for anyone who already writes Rust and wants a working pattern for one task, not a language course, because every recipe is compiled and tested rather than pasted. Two caveats belong in the same breath. The guarantee that recipes are tested holds for the workspace members and not for the seven excluded crates, so a recipe involving sea_orm, sqlx, leptos or wasm components is documentation you have to verify yourself. And the toolchain documentation is inconsistent today, with the offline instructions and the Makefile pinning different mdbook versions, so follow the Makefile, which is what the development section points at anyway. Anyone wanting a book to learn the language from should treat this as a reference to grep, not as a curriculum.
Frequently asked questions
How do I read the Rust Cookbook offline?
Clone the repository, change into the book directory, install mdbook with cargo at the version given on the page, and run mdbook serve with the open flag. The generated output can also be opened straight from the book subdirectory in a browser.
How are Rust Cookbook recipes tested?
Each recipe is a crate in a single cargo workspace, and the test target runs cargo test across it, followed by a spellcheck script over the book's text. Recipes in the manifest's exclude list are not part of that run.
Which mdbook version does the Rust Cookbook use?
Two are documented on the same page. The offline reading instructions install 0.4.43, while the Makefile's install target installs 0.5.3, and the build and serve targets depend on that Makefile target running first.
Which Rust Cookbook recipes are excluded from the workspace build?
Seven: database recipes for sea_orm and sqlx, a multimedia playback crate, a leptos web crate with its hydrate companion, and a wasm component guest with its host.
What license applies to the Rust Cookbook?
The prose is under Creative Commons Zero v1.0 with a LICENSE-CC0 file at the root, and contributions are dedicated to the public domain by default, while the crate manifests declare MIT OR Apache-2.0 for the code.
Does the Rust Cookbook cover learning the Rust language?
It is a collection of task recipes rather than a language course: each page shows a working pattern for one job using crates from the ecosystem. For the language itself, the page points to rust-lang.org.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/rust-lang-nursery-rust-cookbook)Star history chart for your README
[](https://hysenlabs.com/projects/rust-lang-nursery-rust-cookbook)Was this useful?