Rust Forge is the documentation book for Rust contributors

Supplementary documentation for the Rust project teams

Rust Forge is a repository of documentation for people who contribute to Rust. The README describes it as supplementary documentation useful for members of the Rust programming language, and it is published at forge.rust-lang.org. The word supplementary is the important one. This is not the Rust book, not the language reference, and not the standard library documentation. It is the place where a team records how it works: where its meetings happen, which repositories it manages, which chat platform it uses, how a release procedure is carried out, what a no tools breakage week involves. The audience is narrow and mostly internal to the project, which is exactly why it needed a home. Without somewhere like this, that material ends up scattered across team repositories, chat logs and private notes, where a new contributor cannot find it. The structure mirrors that purpose, since the book is organised by team, with each team owning a section and subpages for larger topics.

mdbook renders the book from src/SUMMARY.md

The toolchain is deliberately small. The repository holds a book.toml, a src/ directory, css/ and js/ directories, a blacksmith/ directory, a build.bash script, a triagebot.toml and a .github/ directory for automation, and the build is driven by mdbook. Locally that means installing mdbook and running one command:

mdbook build

That produces the book. For day to day work the README recommends serving it instead, which starts a local server and rebuilds as you edit:

mdbook serve

The navigation comes from src/SUMMARY.md, the standard mdbook table of contents, and the README notes that mdbook creates the folder and file for a new page automatically when you build. That is why adding a team is a two step job: a list entry in the summary, then a file that mdbook materialises for you. The consequences for a contributor are worth stating plainly. The whole site is a static book, so there is no application logic to break, but the shape of the book, its ordering, its navigation and its internal link graph are all defined by one summary file, which makes that file a point of contention when several teams add sections at once. The css/ and js/ directories hold custom presentation, and the js/ directory in particular carries behaviour the README explains, which is a piece of the site you can break for everyone else.

Blacksmith fetches release history and is disabled by default

One page in the book needs data that does not live in the repository: a historical list of Rust releases. That is what blacksmith does, according to the README. It runs before the book is built, downloads information about Rust releases, and uses it to render a page of historical releases. The catch is compilation time, since the tool takes a while to compile and run, so it is disabled by default. Turning it on is a matter of an environment variable, with the README specifying RUN_BLACKSMITH=1 alongside either mdbook serve or mdbook build. The design choice is defensible. A release history page is a nice-to-have for most contributors and a one-off cost for everyone, so paying that cost on every local build, and on every CI run, would be a poor trade. The consequence for a newcomer is that a page which looks empty locally may simply be a page that needs the tool enabled, and debugging a missing page means checking the environment variable first. The tool also means the book has a network dependency at build time, which is worth remembering when a release history page is the thing that fails.

CI checks that your intra-doc links still resolve

Documentation in a book of this size rots through broken links rather than through wrong prose, so the project checks it mechanically. The README states that CI automatically checks whether all intra-doc links in the Forge markdown files are valid, and that the same check can be run locally. The local tool is mdbook-linkcheck2, installed with a pinned version and a locked dependency set:

cargo install [email protected] --locked

After that, the check runs as part of the normal build or serve command, so there is no separate check step to remember. This is a small but meaningful design decision. Link checking is folded into the same command that renders the book, which means a contributor who builds locally gets the same failure the CI system will produce, and the feedback arrives before a pull request rather than after it. The cost is that the local build becomes slower and needs network access, and a contributor working offline will find the check failing for reasons that have nothing to do with their edit. The pinned version in the install command matters for the same reason: the check should behave the same on a laptop and in CI, otherwise you get false confidence from a local pass.

A team needs permissions before it can publish a section

Adding a team to the book is documented in three steps, and the first one lives in another repository. Any Rust team, working group or project group can have a section, but before anything can be merged the team has to be added to a file in the team repository so that it gains permissions. The README links that file, repos/rust-lang/rust-forge.toml, in the rust-lang/team repository. Only then does the team add itself to the book, by adding a list entry to src/SUMMARY.md with a filesystem and URL friendly version of the team name, pointing at an index page under src/. The README explains that running mdbook build creates the folder and the file, and that general information such as meeting locations, managed repositories and chat links belongs in that index, while larger topics become subpages. Two more conventions matter. Teams are responsible for merging their own content, so the book does not have a single maintainer approving every page, and each team is asked to add itself to the assign.owners section of triagebot.toml so the triage bot can auto-assign someone from the team. The practical implication is that a new team cannot simply open a pull request against the book, which is a deliberate governance choice and also the first hurdle for a newcomer.

The JavaScript in js/ has to satisfy standard

Forge uses JavaScript to display dates for releases and for the no tools breakage week, so the behaviour of the site is not entirely in the markdown. The README is specific that changes to that JavaScript must match the standard style, and gives the two ways to install the formatter, one for yarn and one for npm:

yarn global add standard

npm install --global standard

Formatting the directory is then a single command:

standard --fix js/

This is a small but revealing part of the project. There is no bespoke lint configuration to learn and no separate toolchain beyond a globally installed formatter, which means the bar for a first contribution touching the front end is low, as long as you run the formatter. What the convention does not cover is what happens if two teams edit the same script, since there is no test suite described in the README for the JavaScript, only the style check. The style rule is the only automated guard on that directory, and a page that renders a date wrongly would not be caught by it. In practice that means the JavaScript layer is small, shared, and worth treating carefully even though the tooling around it is simple.

The Forge against a team README in the team repository

The real alternative to putting notes in the Forge is putting them in the team own repository, usually in a README or a docs directory. The difference in approach is where the publishing happens. A repository README lives next to the code it describes, is versioned with that code, and needs no build, no summary file and no permissions outside the team. That makes it the cheaper option for a team that only needs a few notes, and it keeps the notes in the same pull request review as the code they explain. Against that, a repository README is invisible to anyone who is not looking at that repository, which is precisely the discovery problem the Forge exists to solve: a contributor who does not yet know which team owns a question has no way to find the answer. The Forge inverts that, publishing everything into one navigable book with a table of contents, a search index and CI checks for broken links, at the cost of a build step, a permissions handshake, and shared ownership of the table of contents. A sensible split is to keep material that only makes sense to the team inside the team repository and to move anything intended for the wider community of contributors into the Forge, where the search and navigation will actually find it.

Apache-2.0 alongside MIT, and the infra team on the hook

The repository carries two licence files, LICENSE-APACHE and LICENSE-MIT, which is the usual Rust convention of offering the same code under either choice. Documentation under those terms can be reused in other projects without imposing the conditions of a copyleft licence, and the pairing is worth noting for anyone copying pages into a downstream handbook. On maintenance, the repository is not archived and the last push was on 2026-10-19, with no GitHub releases, which is normal for a book rather than a library: there is nothing to version, since the published site is the artefact and it is rebuilt from main. The README states that the Rust infra team is responsible for maintaining the Forge, ensuring that its build and publish system works and coordinating technical issues with teams, and that division of labour is what makes the self-service team model work. The cost of a change lands unevenly as a result. Adding a page is a pull request merged by the owning team, with no gatekeeping from the infra team beyond the build. Changing the build, the link checker or the JavaScript layer is a smaller number of people who can do it well, and the build.bash script and blacksmith/ directory sit in that category.

Editorial conclusion

Adopt the Rust Forge model if you are documenting a project that has no home for such notes, and expect to publish through mdbook with a summary file and a link checker in CI. Do not expect it to be a general purpose documentation site, since the book is organised around Rust teams and their working groups, and content is owned and merged by each team. Verify three things first: that your team can obtain permissions in the team repository, since adding a team requires a pull request there before anything can be merged into the book, that CI link checking passes for your pages, and that the dual Apache-2.0 and MIT licence files in the repository match the terms your project already applies to its documentation.

Frequently asked questions

Official sources

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