Book Editing and Example Code Development
Book Editing and Example Code Development

Type just⮳ (a tool similar to make⮳) in your favorite shell to lists all commonly used recipes during book editing and example code development.

Use just serve to preview the book by serving it locally on http://localhost:3000⮳.

To add or edit the book, simply update or add a .md file in the appropriate src⮳ subfolder, then add a link in SUMMARY.md⮳.

  • Add Rust code examples under crates/ex/<crate_name>/tests/<folder e.g. category>⮳.
    • Make sure to format your code (just fmtall or cargo +nightly fmt --all), check it compiles (just buildall or cargo build --all-targets), lint it (just clippyall or cargo clippy --all-targets), and test it (just testall or cargo test --test <name> for an individual example). You may also cargo run --example <name>.
    • Include your code example in the Markdown via {{# include /path/to/file.rs}} within pairs of triple backticks.
  • You may write very short examples directly in the Markdown (but they won't be be formatted / linted automatically).
  • rust language code blocks in the Markdown will automatically get a play button, which will execute the code in the Rust Playground⮳ and display the output just below the code block. Adding the mdbook-runnable attribute forces the play button to be displayed when ignore⮳ is set.
  • The Rust playground only supports the top 100 most downloaded libraries and libraries used by the Rust Cookbook. noplayground⮳ removes the play button if a code block does not work on the playground.
  • Example projects that are too complex to be inserted in the book itself (e.g. that include multiple modules) should be added as separate folders below crates/xmpl. Use cargo new or cargo init to create packages as usual. Insert a link to the appropriate GitHub page in the markdown.

Verify the markdown is properly rendered using just serve or mdbook serve --open. Pushing a commit to the main branch on GitHub will trigger a GitHub Action workflow that checks formatting / linting, builds / tests all examples, then deploys the book to GitHub Pages.