The Rustonomicon builds with mdBook and admits it is still a draft

What the Nomicon covers, and who it is written for

The repository describes itself as The Dark Arts of Advanced and Unsafe Rust Programming, and the README repeats that subtitle before shortening the name to the Nomicon.

Its stated job is narrow: dig into the awful details needed to write correct Unsafe Rust programs. A reader who wants everyday Rust guidance gets nothing here, and a reader who writes one unsafe block a year has little reason to come back.

Above the text sits a note saying this is a draft document and may contain serious errors. That is not boilerplate, because it is the first claim the project makes about its own accuracy. The same file then asks readers to open issues about anything and to send pull requests for things they would like to fix.

The repository is CSS first and holds no Cargo manifest

The primary language listed for rust-lang/nomicon is CSS, and the top-level tree explains why: a `theme/` directory for styling, a `book.toml` for metadata, and a `src/` directory of chapters rather than Rust source.

There are 9 entries at the top level, and none of them is a Cargo manifest.

.github/
.gitignore
CITATION.cff
LICENSE-APACHE
LICENSE-MIT
README.md
book.toml
src/
theme/

Nothing in that list is a crate, so nothing in it gets added to a Cargo.toml. The only Cargo involvement in the entire workflow is installing the renderer, and that single command pins nothing.

Two licence files, `LICENSE-APACHE` and `LICENSE-MIT`, sit beside `CITATION.cff` at the top level while the repository licence field reads Apache-2.0, so read the terms attached to any passage before copying it elsewhere. The last push to master was on 2026-08-17.

Building locally takes 3 commands and pins nothing

Building the Nomicon requires mdBook, and the README walks the path from a clean checkout to a rendered book in 3 commands. Install the renderer first:

cargo install mdbook

Then render every chapter:

mdbook build

Output lands in the `book` subdirectory, and opening `index.html` in a browser is the whole review step. For a shorter editing loop, the `--open` flag builds first and then opens the index page in your default browser if the process succeeds, which the README compares to `cargo doc --open`:

mdbook build --open

Nowhere in that sequence is a version given, so the renderer floats. Two people working from the same commit on different days can end up with different output from identical Markdown, and neither of them can say which renderer produced a given page.

mdbook test compiles the samples and stops there

A second sub-command covers the Rust inside the chapters:

mdbook test

That command tests all code samples contained in the book, and it is the full extent of the automated checking around the text. Across the 5 code blocks and 6 command lines in the README, two sub-commands and one flag appear, and every one of those blocks is shell: the Rust samples live in the chapters under `src/`, not in the README.

A wrong sentence about unsafe Rust therefore survives `mdbook test` exactly as it survives `mdbook build`, because neither command reads English. For a book whose subject is the corner of the language where a line that compiles is not the same as a line that is correct, the automated net stops precisely at the claims a reader trusts most.

The link checker comes from rust-lang master, not from this repository

Broken links are found with `linkcheck`, and this repository does not vendor the tool. The README downloads the script from the compiler repository at run time and then points it at the book:

curl -sSLo linkcheck.sh https://raw.githubusercontent.com/rust-lang/rust/master/src/tools/linkchecker/linkcheck.sh
sh linkcheck.sh --all nomicon

That choice produces 2 consequences. The check is pinned to nothing, since it follows whatever sits on the `master` branch of rust-lang/rust when you run it, so an unchanged commit of the Nomicon can pass today and fail next week after an upstream move. And the script lands in your working directory as a file the repository does not track, with `.gitignore` present at the top level although the README does not say whether that filename is covered.

Contributors get to run the same checker the compiler project uses, at the cost of a dependency they cannot inspect from this repository alone.

Large changes need an issue before the pull request

The contributing section is unusually open for a book that warns about its own accuracy: open issues about anything, send pull requests for things you would like to fix or change.

One condition sits on top of that. If your change is large, open an issue first, so the project can decide whether it is something they would accept before you assemble the pull request.

The order matters for anyone planning a chapter rewrite, because the gate comes before the work instead of after it. The README names no reviewer, no review process and no turnaround, so the only commitment stated anywhere is that large work gets discussed before it is written.

Undocumented gaps in publishing, pinning and continuous checks

Build output goes into the `book` subdirectory, the homepage listed for the repository is https://doc.rust-lang.org/nomicon/, and nothing in the README documents how a rendered directory reaches that address. A reader who needs a fixed copy has to build from master and keep the output themselves.

3 gaps follow from that. No version of the text is named anywhere in the repository, so two checkouts of master on the same afternoon are not guaranteed to be the same book. No compatibility statement ties the chapters to a compiler version, which matters for a subject where the toolchain is the enforcement mechanism. And a `.github/` directory sits at the top level without the README saying what runs inside it, so the continuous checks behind the book are not discoverable from the files a reader is pointed at.

For a tool or a library this would be a blocker, since there is nothing to depend on: no manifest, no published artifact, nothing to put in a lockfile. This is a reading project rather than an installable one, and judging it by dependency rules produces the wrong answer.

Why mdBook renders chapters where cargo doc renders comments

One comparison sits in the README, and it is instructive. `mdbook build --open` is described as working just like `cargo doc --open`, which places two different toolchains side by side.

Documentation generated by Cargo is read out of Rust source comments and stays tied to a specific crate version, while mdBook consumes a `book.toml` and a `src/` directory of Markdown and stays tied to no crate at all. That difference explains the extra sub-command: nothing in a Markdown build would otherwise compile the samples, so `mdbook test` has to run as a separate pass.

The honest alternative for a reader who only wants the text is the rendered book online, and picking it costs version drift, since the hosted pages and a local build of master are not guaranteed to match. Building locally gives you the drift instead, in the form of a renderer that floats and a toolchain you chose yourself.

Editorial conclusion

This is a book rather than a dependency, and it earns a place on the desk of anyone about to write unsafe Rust. People who already know safe Rust get an explanation of rules the compiler does not enforce; everybody else will find the coverage too thin. Before trusting a chapter, build master with `mdbook build`, compare a passage against the compiler version you target, and treat the README's own warning about serious errors as the starting assumption, not the last disclaimer. That draft status is the project's own claim, repeated at the top of the file.

Frequently asked questions

Official sources

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