mdBook Utilities

Project status and roadmap are actively maintained.

This is a Work In Progress. The command-line interface (CLI) and underlying API are subject to change. A summary of recently released changes is found in RELEASES.md. You may also consult TODO.md.

What is mdbook-utils? What is it used for?

The mdbook-utils command-line tool manages links, reference definitions, and code blocks in large collections of Markdown files, especially mdbook source directories. It is the companion tool for the Rust How-to book (github).

mdbook-utils is useful for the following:

• centralize all reference definitions in one file to make Markdown files more readable and ease link maintenance,
• replace simple Markdown links by badges,
• identify duplicate or broken links,
• identify Markdown files not listed in SUMMARY.md,
• identify unused Rust code examples,
• generate a sitemap from pages listed in SUMMARY.md and present in the selected HTML renderer output,
• extract fenced code bocks embedded into the Markdown to separate files for easier formatting, debugging and testing,
• replace code examples by mdBook #include statements,
• conversely replace mdBook includes by the file contents.

Installation and Usage

Consult the User Guide for installation and usage instructions.

Command-line Subcommands

• refdefs: Manage reference definitions.
  • write: Write existing reference definitions to a file.
  • generate: Generate reference definitions: GitHub badges (--badges, --badge-style <STYLE>) or definitions from the Cargo.toml dependencies of the code examples (--from-dependencies).
• links: Manage links.
  • write-all: Write all existing links to a Markdown file.
  • write-inline: Write all existing inline/autolinks to a Markdown file.
  • duplicate-links: Identify duplicate links/labels.
  • broken-links: Identify broken links.
• markdown: Manage code blocks and includes.
  • extract-code-examples: Extract Rust code examples to separate files.
  • replace-code-examples-by-includes: Replace code examples with {{#include}} statements.
  • replace-includes-by-contents: Resolve {{#include}} statements.
  • remove-includes: Remove {{#include}} statements.
  • identify-files-not-in-summary: Find .md files missing from SUMMARY.md.
  • identify-unused-rs-examples: Find .rs files not included in any .md file.
  • generate-crates: Generate an index of the crates linked from the book.
  • generate-categories: Generate an index of the crates.io categories linked from the book.
• sitemap: Generate a sitemap.xml file (--base-url, --map-index FROM:TO).
• debug: Write the Markdown parser events to a file.

Run mdbook-utils <command> --help for the options of each command.

Environment Variables

• MARKDOWN_DIR_PATH: Path to the Markdown source directory (default: ./src/).
• BOOK_ROOT_DIR_PATH: Path to the book's root directory containing book.toml (default: .).
• BOOK_HTML_BUILD_DIR_PATH: Path where mdbook outputs HTML (usually ./book/ for one renderer or ./book/html/ for multiple renderers).
• BOOK_MARKDOWN_BUILD_DIR_PATH: Path where the Markdown renderer writes expanded Markdown.
• CARGO_TOML_DIR_PATH: Directory where a Cargo.toml can be found.
• DEFAULT_DEST_DIR_PATH: Default directory for generated mdbook-utils files.
• BASE_URL: Base URL for sitemap generation (defaults to output.html.site-url in book.toml; there is no placeholder default).
• RUST_LOG: Logging level (error, warn, info, debug, trace).

Configuration via book.toml

mdbook-utils uses mdBook's book.toml configuration for the Markdown source directory (book.src) and renderer output directories (build.build-dir and [output.*]). Relative paths are resolved from the directory containing book.toml, selected by BOOK_ROOT_DIR_PATH.

For a path with a command-line option, the precedence is command-line option, matching environment variable, book.toml, then that command's default. A missing book.toml is optional; an unreadable or malformed file produces an error when resolution reaches it. mdBook enables HTML when no renderer tables are configured. One renderer writes directly to build.build-dir; with multiple renderers, each writes to a renderer-named subdirectory such as html or markdown.

book.toml is the only TOML configuration source. There is no separate mdbook-utils TOML file.

Development and Testing

just test runs the unit, integration, and doc tests, and the mdBook tests of the user guide and test_book. For the Rust tests alone, run cargo test --all-targets --locked. Unit tests live next to the code in src/; the tests/ directory holds integration tests that run the compiled binary and the public API against temporary directories and the fixtures in tests/fixtures/. See the user guide's contributing section for details.

Public API

mdbook-utils' underlying library also exposes a public API that may be used from your code.

Key Links

mdbook-utils (github) (docs.rs) (crates.io) (user guide)