Open-source project
rust-lang/rust-by-example avatar
rust-lang/rust-by-example

rust-by-example: an mdBook with a network-bound editor

Learn Rust with examples (Live code editor included)

8,154 stars1,578 forksHandlebarsApache-2.0

At a glance

What is it?
Rust by Example is a book of runnable Rust examples built with mdBook, with a live code editor embedded in the page and translations contributed in-tree or in separate repositories. It has no releases, its last push was on 2026-09-29, and running the examples is the one part that needs an internet connection.
Who is it for?
Adopt rust-by-example if you learn by reading working code and you accept that running the snippets requires an internet connection. Do not expect it to work offline or to be a packaged artefact, because there are no releases and the examples are the source.
Can I use it commercially?
Yes. Apache-2.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 47 days ago.
What is it written in?
Mainly Handlebars, 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.

From daily snapshots

Star history

  • rust-lang/rust-by-example8,154 ★ · +42
Star history
Repository2026-09-222026-11-15
rust-lang/rust-by-example8.1k8.2k

42 Stars in the last 54 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

The examples are the source, and the editor needs a network

The repository description is one line: Learn Rust with examples, live code editor included. Everything else follows from that framing.

The content lives in `src/`, rendered into a book by mdBook, with the configuration in `book.toml`. Reading it online is a URL, and building it locally is five commands:

bash
git clone https://github.com/rust-lang/rust-by-example
cd rust-by-example
cargo install mdbook
mdbook build
mdbook serve

The limitation is stated plainly right after that: to be able to run the examples you must be connected to the internet, while you can read all content offline.

That split is the design. The text is static and portable, and the runnable part is a remote execution path. So the project works on a plane for reading and does not work on a plane for running, and a reader who copies a snippet out of it is copying code they cannot verify until they are back online.

There is a small inconsistency in the URLs too: the repository metadata points at the stable documentation path, doc.rust-lang.org/stable/rust-by-example/, while the README sends you to doc.rust-lang.org/rust-by-example/ without the stable segment.

The gettext warning is expected, and the README says ignore it

The build emits one warning that the README tells you to ignore safely:

text
WARN The command `mdbook-gettext` for preprocessor `gettext` was not found, but is marked as optional.

The word that matters is optional. mdBook knows about a gettext preprocessor, this repository does not install it, and mdBook reports the absence rather than failing. That is what the warning is telling you: the internationalisation pipeline is wired into the book configuration, but the tooling is only needed when you build a translation.

For most readers the sequence is: install Rust, clone, `cargo install mdbook`, build, serve, and ignore that line. For anyone producing a translated build, the same warning becomes the thing to fix, because that is when the preprocessor is doing work.

The consequence for evaluation is that a clean first build looks like it has one problem and does not. Reading the README's warning in advance is the difference between spending ten minutes on it and spending ten minutes wondering.

A theme directory is why the primary language is not Rust

The repository's primary language is Handlebars, not Rust, and the top-level listing explains it: there is a `theme/` directory beside `src/`, `po/`, `book.toml` and the licence files.

A theme is a set of templates, and Handlebars is what mdBook templates are written in. So the language statistic reflects the presentation layer of the book, with the examples as the content that those templates render.

The rest of the tree is project furniture: `.gitattributes`, `.github/`, `.gitignore`, `CODE_OF_CONDUCT.md`, `CONTRIBUTING.md`, `TRANSLATING.md`, two per-language translation guides, and both licence files. There is no `examples/` directory and no application, which is consistent with a repository whose output is a website rather than a program.

MDBOOK_BOOK__LANGUAGE selects a translation from po/

Translation is a build-time switch rather than a separate edition. If there is a translated resource in the `po/` directory, it can be specified through `MDBOOK_BOOK__LANGUAGE`:

bash
MDBOOK_BOOK__LANGUAGE=ja mdbook build
MDBOOK_BOOK__LANGUAGE=ja mdbook serve

The example uses `ja` for Japanese, and the same variable would carry whatever language code matches a directory in `po/`. This is the gettext convention, which is why the preprocessor warning above exists: the translation files are gettext catalogues, and mdBook has a preprocessor that reads them.

The consequence is that a translation is not a fork of the content. The Rust source stays single, and the translated strings sit beside it in `po/`. A translator's job is therefore additive.

Two per-language guides are kept in this repository, `TRANSLATING_JA.md` for Japanese and `TRANSLATING_ZH.md` for Chinese, and the general process is in `TRANSLATING.md`.

Five other translations are separate repositories

After the in-tree guides, the README lists translations that live elsewhere, each as its own repository: Bulgarian at kberov/rust-by-example-bg, French at Songbird0/FR_RBE, Russian at ruRust/rust-by-example, Vietnamese at EyesCrypto-Insights/rust-by-example-vn and Portuguese at nazarepiedady/rust-com-exemplos.

So the translation model has two halves, and they carry different costs. A language with a guide in this repository and catalogues in `po/` is built with one `MDBOOK_BOOK__LANGUAGE` command. A language listed as a separate repository is a fork someone maintains, and it tracks the upstream content only as far as its owner keeps it in step.

That is a real difference for a reader choosing a language, and the README does not explain it. A translated edition in its own repository can lag, and nothing in the listing says when it was last synchronised.

The Portuguese repository name, rust-com-exemplos, also shows that a translation is free to rename the project, which is another sign that these are independent copies rather than build outputs.

Apache-2.0 or MIT, and contributions come dual by default

The licence section is the longest part of this short README, and it is more specific than a single licence line.

Rust by Example is licensed under either of the Apache License, Version 2.0, with LICENSE-APACHE at the repository root, or the MIT license, with LICENSE-MIT, at your option. Both files are committed, so choosing is a matter of which one you rely on rather than of which one exists.

Then a clause about contributions: unless you explicitly state otherwise, any contribution intentionally submitted for inclusion shall be dually licensed as above, without any additional terms or conditions.

That is the standard dual-licensing arrangement and it is worth reading before sending a patch, because the default is a grant under both licences with no carve-out for a company that needs one. A contributor who wants different terms has to say so explicitly.

The two files at the root are the fuller statement of what you may do with this content, since the GitHub repository metadata lists Apache-2.0 alone.

No releases, and a bot that works the issue tracker

The maintenance picture is short. There are no GitHub releases, and the last push was on 2026-09-29 with the repository not archived.

For a book that is the normal shape. There is no artefact to cut, because the artefact is a website built from `src/` on demand, and the history of the examples is the history of the repository. Nothing is published to a package registry, so there is no version to depend on.

The one automation file at the top level is `triagebot.toml`, which suggests a bot helps with triage on the issue tracker. Alongside it sit `CODE_OF_CONDUCT.md` and `CONTRIBUTING.md`, and the README's contribution section is a single sentence pointing at the latter.

The README is also where the project's social links sit, and there are none beyond GitHub: contribution through `CONTRIBUTING.md`, translation through `TRANSLATING.md`, and nothing else. For a repository that many people read while learning, that is a small surface by design.

Editorial conclusion

Adopt rust-by-example if you learn by reading working code and you accept that running the snippets requires an internet connection. Do not expect it to work offline or to be a packaged artefact, because there are no releases and the examples are the source. Before you build the book yourself, install mdBook with cargo install mdbook, and read the translation guide for the language you want, since only some translations are kept in this repository.

Frequently asked questions

What is Rust by Example?

It is a book that teaches Rust through runnable examples, with a live code editor included, built from `src/` with mdBook and configured by `book.toml`. You can read it online at doc.rust-lang.org/rust-by-example/ or build and serve it locally with mdBook.

is rust by example good

The repository does not make that judgement itself. What it states is the trade it chose: all content can be read offline, but running the examples requires an internet connection because the live code editor executes them remotely. It ships no releases, so it is a reading resource rather than something you depend on as a package.

rust by example vs the book

The README does not compare itself with any other book, so that comparison has to be made from what each offers. Rust by Example is example-driven, with runnable snippets in a live editor, translations via `MDBOOK_BOOK__LANGUAGE` and gettext catalogues in `po/`, and per-language translation guides for Japanese and Chinese.

Official sources

  1. Issues
  2. License: Apache-2.0
  3. Project website
  4. README
  5. rust-lang/rust-by-example on GitHub
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.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/rust-lang-rust-by-example.svg)](https://hysenlabs.com/projects/rust-lang-rust-by-example)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/rust-lang-rust-by-example.svg)](https://hysenlabs.com/projects/rust-lang-rust-by-example)

Was this useful?