This introduces a new local GitHub action for installing Debian
packages. I noticed that it often takes several minutes to install a few
small packages, and a large part of that time is spent updating the man
page database:
2025-09-20T11:39:25.3001853Z Setting up yapf3 (0.33.0-1) ...
2025-09-20T11:39:25.3045329Z Processing triggers for libc-bin
(2.39-0ubuntu8.5) ...
2025-09-20T11:39:25.4420933Z Processing triggers for man-db
(2.12.0-4build2) ...
2025-09-20T11:41:42.8522570Z Processing triggers for install-info
(7.1-3build2) ...
Excluding the documentation files should make the man-db run much
faster. Compare these two runs:
*
[Before](https://github.com/google/comprehensive-rust/actions/runs/17879390708/job/50845084995):
2m 41s.
*
[After](https://github.com/google/comprehensive-rust/actions/runs/17880418155/job/50847334471):
11s.
When cargo xtask install-tools --binstall is used, precompiled binaries
are fetched if available.
Triggers a regular (compilation) install if binary releases do not
exist.
This is now configured to be used by the CI to speed up the build and
deploy workflows where possible.
Currently binary packages exist for:
- mdbook
- mdbook-pandoc
### Background
Comprehensive Rust requires a number of tools to be installed (e.g.
mdbook and mdbook-course). As mentioned in #2509 (and discussed in
#2469) it would be nice to have a cross platform command for installing
these dependencies. Currently these are installed using a shell script
(`install-mdbook.sh`) but this isn't truly cross platform e.g. for
Windows users.
### Xtask
[xtask](https://github.com/matklad/cargo-xtask) outlines an approach for
automating tasks in a Rust project. It involves using cargo's aliasing
feature to allow us to run commands like `cargo xtask <some task>` to
perform adhoc tasks via a Rust binary that we might otherwise need a
shell script for.
In this PR we add support for a `cargo xtask install-tools` command that
will replace the `install-mdbook.sh` script and install the dependent
tools. We can potentially extend it to support for other tasks e.g.
`cargo xtask fmt`.
---------
Co-authored-by: Eric Githinji <egithinji@google.com>
Move mdbook installation into a script and use exact versions from the
CI.
Update README.md to instruct developers to use the same versions as the
CI to sync both environments.
This is related to #2620 and it fixes#2588
Once a new version of Pandoc is released that includes
https://github.com/jgm/pandoc/pull/9204 and
https://github.com/jgm/pandoc/pull/9353 (both merged), this will fix the
emoji and symbol rendering issues in #1708.
It doesn't seem to be possible to set fallback fonts with
`luatexja-fontspec` (used to configure CJK fonts), which results in some
missing symbols in the translations but at least renders the emoji
properly.
Closes#1708
Before, we only installed and ran `mdbook-pandoc` when publishing the
course — which means that a PR change could accidentally break the
publish workflow. We now test that it works on every PR.
From a discussion in #1704.
This version has much improved support for the translation of code
blocks. See https://github.com/google/mdbook-i18n-helpers/issues/95 for
details.
Most PO files won’t need any update since most of them don’t translate
the comments in the code blocks. Those that do, can run
`mdbook-i18n-normalize` when they feel like it.
This also ports over the latest changes to `book.js` and `index.hbs`.
We probably need to come up with a more systematic way of doing this,
e.g., we could store our changes in a patch and automatically attempt to
apply it onto the latest upstream files.
In v2 of the course, I'd like to include an estimate of the time to be
spent on each segment in the Markdown file. I think a good place for
such metadata is in the frontmatter.
For review purposes, though, I just want to display that information.
So, this is a start at a new mdbook preprocessor that just separates out
the frontmatter and includes it in a `<pre>` block. Eventually, I'd like
to parse it and put the time in the speaker notes.
---------
Co-authored-by: Martin Geisler <martin@geisler.net>
This updates our `mdbook` version to the latest version in Git. I copied
the `index.hbs` file from that version and back-ported our changes into
it. I checked English and Danish locally and they both look fine.
The new version has support for right-to-left languages:
https://github.com/rust-lang/mdBook/pull/1641.
We have an in-progress Persian translation. Download the `fa.zip`
artifact after building the PR to check how it looks. I checked Persian
locally and it looks mirrored like I expect (but we will need someone
who can read Persian to actually verify this).
Fixes#1164.
I have created PRs to normalize all PO files to the new version of
mdbook-i18n-helpers. Simultaneously, we need to update the version used
to publish the course.
This is indirectly part of #330.
I also updated `book.js` and `index.hbs` to the latest versions while
keeping our local modifications.
I tested this locally with `mdbook serve` for both English and
Brazilian Portuguese and everything seems to work fine.
The i18n-helpers are now available as a stand-alone crate:
https://crates.io/crates/mdbook-i18n-helpers.
Because we cache the Rust binaries in our GitHub workflows, I bumped
the cache prefix to ensure we use a clean cache. Otherwise, Cargo
won’t install the new binaries in mdbook-i18n-helpers because it sees
the old ones from this repository.
* Update mdbook to 0.4.28
This version contains https://github.com/rust-lang/mdBook/pull/1986 which will allow us to test the code in each translation.
* Fix formatting in Korean translation
The extra code block made `mdbook test` fail.
* Extract common build steps to composite actions
This allows us to repeat ourselves less across the different jobs.
I also tested using a “reusable workflow” to factor out the common
steps. However, this starts a separate job without a shared
filesystem, which in turn requires us to upload/download artifacts
when we want to use them in several jobs. The artifacts are downloaded
one-by-one and this adds delays and extra steps to all jobs.
* Move Rust cache setup to its own build step
This made it easy to consistently setup the caching of our nested
projects via the “workspacs” config key.
Martin Geisler
michael-kerscher
Andrew Walbran
Eric Githinji
Max Heller
Martin Geisler
Darkhan Kubigenov
Dustin J. Mitchell