A Week in the Rust Cookbook: Cleanup, a Redesign, and Tests That Guard Both

TL;DR. Between October 24 and 29 I merged about 35 PRs into the Rust Cookbook. That is roughly 10,000 lines added and 3,000 removed across 700 files. The week had three threads. First, I retired old and unmaintained dependencies and moved recipes into standalone crates. Second, I rebuilt the book’s front end with search, cards, and accessibility checks. Third, I added tests so the structure stays correct without anyone remembering to check it. This post is the ledger.

Retiring dependencies

The cookbook’s value is that every recipe compiles. The corollary is that every recipe pins you to a crate, and crates age. The first half of the week was a sweep through the ones that had aged out:

  • Removed error-chain, replaced lazy_static with std::sync::LazyLock, and replaced the threadpool recipe with rayon.
  • Swapped memmap for memmap2, and ansi-term (unmaintained) for nu-ansi-term.
  • Pointed byteorder and the bitfield recipes at what std now offers.
  • Updated reqwest and rusqlite to current versions, and removed the unused root dependencies petgraph, sha2 and serde_derive.
  • Moved the whole book to Edition 2024, including the older edition2018 and edition2021 blocks in the text, and added a cargo xtask fmt-md step so the markdown snippets follow 2024 style.

The pattern in the rest of the sweep was moving recipes out of the root Cargo.toml and into their own standalone crates: science, logging, web scraping, ANSI colors. Each recipe then declares exactly what it needs. That unlocked a follow-up. Moving crates out had dropped them from the root [dependencies] table, which is the list the Rust Playground reads. I added them back as optional entries, so the playground still sees the names even though nothing compiles them.

The week’s new content was small by comparison, but it fits the same theme:

  • jiff datetime recipes, plus a chrono / time / jiff comparison page to help readers choose between them.
  • RustCrypto hashing recipes, with a ring vs. RustCrypto comparison. The basics sit beside ring, and the trait-level recipes have their own “Extensible RustCrypto” page.

A faster test loop

On October 24 I turned on rust-skeptic’s binary cache for the cookbook’s example tests. A cold run takes about 85 seconds and a warm run about 5. That made the rest of the week much easier, because I ran the whole book’s tests far more often than I would have otherwise.

The redesign

Issue #882 was the big one: the book worked, but it was hard to find things in. It landed as a series of small PRs:

  • Build-time chips. A new mdbook-chips preprocessor renders crate and category pills at build time. The crate chip has a copy button for the Cargo.toml line.
  • Theme. Recipe cards, cleaner headings, previous/next titles, snippet buttons, and contrast fixes. Topic and recipe cards got index-card tabs that track their place in the list.
  • Search. A Cmd/Ctrl+K overlay backed by a build-time index of crates, topics and recipes.
  • Landing page. Topic cards, a crate index, and an alphabetical recipe index.
  • Ordering. Topics follow the sidebar and table rows follow their pages. The long tables are split into labeled groups with dividers, and the groups are searchable.
  • Feature banners. One consistent banner tells you which Cargo features a recipe needs. The chip’s copy button then copies the line with those features, which it previously did not. That was a real bug: a reader could paste a dependency line that didn’t compile.

Tests that guard the structure

A redesign that depends on every contributor following the conventions will drift. So most of the week’s PRs came with a test that fails when the convention is broken:

  • Every recipe must be listed in its section table, in sidebar order.
  • Badges and categories must exist.
  • A recipe that includes code from a crate that enables features of a dependency the code uses must carry a feature banner. A banner must not name a feature the crate doesn’t enable. I found the right features by compiling each binary with one feature removed at a time.
  • Accessibility: axe runs in every theme on pull requests, with scripted keyboard and focus checks for the search dialog.
  • Dependabot now opens dependency update PRs, with major updates in their own PRs. Eleven of them landed during the week. CLAUDE.md in the repo now says new recipes are standalone crates, and that root bumps just merge while breaking ones need a migration.

The markdown carries the exceptions rather than a list in the test code. For example, <!-- not-a-recipe --> marks the comparison guides, and <!-- needs-no-features: dep --> marks recipes that use a dependency without its features. A stale marker fails the build. The rules are written up in a new “Book checks” section of CONTRIBUTING.

Other contributors

Shreyas S grouped the build-tooling recipes by language this week. Having a second pair of eyes on the structure while I was changing it was welcome.

What’s next

The book now has a single source for its mdBook version, search, tests, and an automated way to keep dependencies fresh. That makes the next step easier: more new recipes, now that adding one is a matter of writing a standalone crate and the checks tell you what you forgot.