Rust patterns: the book, the template, and the optional installs around mdbook

It is a book first, with a repository behind it

The thing most people encounter is not the repository. The front page describes an open source book about design patterns and idioms in the Rust programming language, and offers it in two forms: readable at a hosted address, and downloadable in PDF format from a separate link. Everything in the repository exists to produce those two artifacts. That framing matters for anyone deciding what to expect. This is not a crate you add to a project, and there is no API to call; it is prose about a language, versioned in the same way prose can be. The practical consequence is that the hosted book and the PDF may correspond to different points in the history, so a passage you read online is not automatically the passage in the commit you have checked out, and the tree is where you go to find out when something changed.

The primary language is a template, not Rust

The repository's dominant language is recorded as Handlebars, which sounds odd for a book about Rust until you look at the tree. There is a template file at the root, and there are theme and styles directories beside it. The root template is a Markdown file, template.md, the sources sit in src/, and book.toml configures the mdbook build.

Building is one command, and one of them starts a server

The build documentation is admirably short, which is a good sign about how little stands between a clone and a rendered book. If you want to build it locally you can run one of two commands in the root directory of the repository. The first builds static HTML pages as output and places them in the /book directory by default. The second serves the book at a local address on port 3000, with the port changeable and the terminal output telling you which port it actually took, and reloads the browser when a change occurs. So there are two shapes of use, a one-shot build that leaves a directory at the repository root, and a watch mode for people editing chapters. The second command is the one you want while writing, and the first is the one you want before publishing.

Each output format is a separate cargo install

The book is built with mdbook, installed by running cargo install mdbook, and that is the only requirement for the core pages. Everything beyond that is an optional preprocessor, and each is installed the same way. There is one for date changes in the footer, one for rendering the book to PDF, and one for translation and internationalisation support. That structure has a practical effect on who can contribute. Someone fixing a typo in a chapter needs one Rust tool and nothing else, while someone verifying that the PDF output is correct needs a second install and, as the next section shows, a good deal more than that. Installing all three because they sound related is the most likely way to create an environment problem that has nothing to do with the book.

The PDF path needs TeX Live, root, and a pinned linux-amd64 download

Rendering the book to PDF is documented as a separate procedure with a real system dependency list. You source a .env file at the repository root to pick up a Pandoc version variable, update the package index, then install a group of TeX Live packages including extras for LaTeX, LuaTeX and CJK text, plus an SVG library and a Noto font set. Finally the specific Pandoc release for Linux on amd64 is fetched and unpacked:

# Source the .env file to get the PANDOC_VERSION
. ./.env

sudo apt-get update

sudo apt-get install -y texlive texlive-latex-extra texlive-luatex texlive-lang-cjk librsvg2-bin fonts-noto

curl -LsSf https://github.com/jgm/pandoc/releases/download/$PANDOC_VERSION/pandoc-$PANDOC_VERSION-linux-amd64.tar.gz | tar zxf -

Three constraints fall out of that. The package installs need root. The Pandoc build you get is pinned to one CPU architecture and one operating system. And the version itself comes from a committed environment file rather than from whatever is installed, which is what makes the output reproducible and also what makes changing it a deliberate act.

Translations are first-class, and they can fall behind the English

The tree carries a directory of translation catalogues alongside the chapter sources, the theme and the styles, and one of the optional preprocessors exists specifically for translation support. The catalogue format is the conventional gettext one, so the book's strings live in a machine-editable form rather than being duplicated by hand into per-language copies. That is a good structure for a book with more than one reader community. The cost is the one every translated project carries: a change to an English source string can leave existing translations describing the previous wording, and nothing in the build forces the two to be reconciled. The front page's own text spells the feature name slightly wrong, calling it i8n support, which is a small indication of how little the wording is load bearing compared with the catalogue directory itself.

A link checker and a formatter treat the prose as code

Three configuration files at the repository root are aimed at the writing rather than the code, and together they say how this book is maintained. There is a formatter configuration, a markdown lint configuration, and an ignore file for a link checker. The link checker is the one with the largest practical effect. A book of this kind is dense with references to other patterns, to language documentation and to external material, and those references rot silently; having a checker means a dead link is something the build complains about rather than something a reader discovers. The formatter means the prose style is settled by a tool rather than by whoever edits a chapter that week, which is the same argument people make about code formatting applied to documentation. It also explains the file spread for what it is, a book that is versioned, reviewed and checked like a small project.

Editorial conclusion

This catalogue of Rust patterns suits someone who wants a readable survey of design patterns, anti-patterns and idioms in one place, online or as a PDF. It does not suit you as an API reference, because it is a book rather than a crate, and the PDF path needs a Linux machine with root access and a pinned Pandoc download. Before contributing, read the contribution guide, check the umbrella issue for what is already planned, and install only the mdbook preprocessor you actually need, since each output format is its own installation.

Frequently asked questions

Official sources

1. Issues
2. License: MPL-2.0
3. Project website
4. README
5. rust-unofficial/patterns on GitHub