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↗ sub-folder, then add a link in SUMMARY.md↗.

  • Add Rust code examples under crates/<section or cats/some_category>/examples/<chapter>/↗.
    • 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 back-ticks.
  • You may write very short examples directly in the Markdown (but they won't be be formatted / linted / tested 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 / linting, builds / tests all examples, then deploys the book to GitHub Pages.

  • Dev Container and Docker.
  • Documentation Generation.
  • Repository Structure.
  • Topics of Interest.