Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Contributing

Pull requests, comments, and issue submissions are actively encouraged!

Repo structure

mdbook-utils is written in Rust and follows the typical cargo package layout.

  • The source code is in the src folder. The main executable is in main.rs and the cli module. It calls the API in lib.rs.
  • A simple test mdbook book is found in test_book.
  • The user guide’ sources are in user_guide.
  • The Dev Container and Docker (Compose) configuration files are found in .devcontainer.
    • devcontainer.json uses Docker Compose (configured in compose.yaml and compose.override.yaml), which in turn runs a container from Dockerfile.
  • .github contains the continuous integration (GitHub Actions) workflow.

Development Setup

Using VS Code

Clone the repo and open the folder in VS Code. Edit .devcontainer/.env if needed. VS Code should prompt you to open the code in a Docker container, which installs Rust tooling automatically. Make sure you have previously installed the following:

Note that opening the code folder in VS Code using Dev Containers may take a little while the first time around.

Other

If you are not using VS Code, install the Dev Container CLI, use docker compose directly (see below), or simply install the required tools on your local machine.

The following works with Ubuntu (including WSL):

sudo apt-get update
rustup update
rustup component add clippy
rustup toolchain install nightly
rustup component add rustfmt --toolchain nightly
cargo install just
cargo install mdbook

Review .devcontainer/Dockerfile for other optional dependencies.

Build and test the code and user guide

The just command runner is configured to simplify compilation and testing.

Type just at a shell prompt for a list of commands:

just clean  # Clean Cargo's `target` and mdbook's `book` folders

just fmt    # Format all code

just check  # Check whether the code can compile

just build  # Build all code and books

just clippy # Scan all code for common mistakes

just test   # Test all code and books

just run <command>  # Run the tool

just doc    # Build and display the `cargo doc` documentation

just serve  # Display the user guide

just prep   # Run all the steps required before pushing code to GitHub

just update # Update Cargo.lock dependencies

Tests

just test runs all Rust tests (cargo test --all-targets --locked) and the mdBook tests of user_guide/ and test_book/.

  • Unit tests are in an inline #[cfg(test)] mod tests at the bottom of the module they cover, under src/.
  • Integration tests are in tests/. They run the compiled mdbook-utils binary (through CARGO_BIN_EXE_mdbook-utils) or the public library API against temporary directories, and check exit codes and the files written. Shared sample inputs are in tests/fixtures/.
  • Give each test a descriptive name and a doc comment that states the behavior it verifies. Avoid unwrap(); return anyhow::Result from the test or use expect() with a message.

Run a single integration test file with, for example, cargo test --test cli_links_and_generate.

Docker Compose

Test the Docker Compose setup used during development (which Dev Containers runs) with:

cd ./.devcontainer
docker compose build   # uses compose.yaml and compose.override.yaml by default
docker compose up -d
# or simply
docker compose up --build -d

Use the following commands to build and test the code and user guide using the Continuous Integration configuration:

docker compose -f .devcontainer/compose.yaml -f .devcontainer/compose-ci.yaml run \
--build --rm mdbook-utils

Publish to crates.io

  1. Manual method
  • Go to crates.io, sign in, and create an API token in Account Settings > API Tokens.
  • Use cargo login <token> to save the token in $CARGO_HOME/credentials.toml.
  • just build; just clippy; just run; just doc; cargo package --locked
  • Review the packaging output in target/mdbook-utils/package or use cargo package --list.
  • When ready, cargo publish --locked --dry-run; cargo publish --locked
  1. Docker Compose method
  • Pass the publish.sh script (and required argument -y) as a command to docker compose run.
  • Pass the CRATES_TOKEN env. variable (which is used by publish.sh) to Docker Compose using --env.
export CRATES_TOKEN="<token from crates.io>"
docker compose -f .devcontainer/compose.yaml -f .devcontainer/compose-ci.yaml run \
       --rm --env CRATES_TOKEN mdbook-utils .devcontainer/publish.sh -y

Release binaries

Pushing a tag such as v0.2.0 runs .github/workflows/release.yml. It builds --release --locked binaries for Linux (x86_64), Windows (x86_64), and macOS (Apple silicon and Intel), packs each with LICENSE and README.md into mdbook-utils-<target>-v<version>.tar.gz (.zip on Windows) with a .sha256 file, runs --help on the unpacked binary, and attaches the archives to a GitHub release. The archive names match [package.metadata.binstall] in Cargo.toml, so users can run cargo binstall mdbook-utils; cargo binstall falls back to building from source when no archive exists.

A manual run of the workflow builds and smoke-tests the archives without creating a release, which is the way to validate packaging without any credentials.

Release checklist and rollback

  1. Update RELEASES.md and the version in Cargo.toml, merge to develop, and wait for CI.
  2. Publish to crates.io with the Build, test, optionally deploy to Pages & publish workflow (or the manual method above).
  3. Push the tag vX.Y.Z to create the GitHub release.
  4. Rollback: cargo yank --version X.Y.Z mdbook-utils hides a bad crates.io release without deleting it; delete the GitHub release and tag if the archives are bad, fix forward, and publish a new patch version.

User guide hosting

The pages.yml workflow builds and tests the guide on every push to develop, writes sitemap.xml into the rendered book with mdbook-utils sitemap --base-url https://john-cd.com/mdbook-utils/, and deploys it to GitHub Pages. The site has no analytics: the guide is documentation for a command-line tool, so no visitor data is collected and no cookie or privacy notice is needed. This can be revisited if usage data becomes useful.

Docker image for CI

CI installs the pinned Rust toolchain and tools directly on the runners (with Swatinem/rust-cache), so there is no published CI image. A prebuilt image would save little time compared to the cache, add a registry to maintain, and need rebuilding for every toolchain update. The .devcontainer image remains for local development and the manual publish method.