Usage

Run the tool without arguments to display the the list of commands:

Tools to manage links, reference definitions, and code examples in Markdown files, especially `mdbook` source directories.

Usage: mdbook-utils [OPTIONS] <COMMAND>

Commands:
  refdefs   Manage reference definitions
  links     Manage links
  markdown  Manage code blocks (embedded examples) and includes
  sitemap   Generate a sitemap.xml file from published HTML pages linked in SUMMARY.md
  debug     Parse the entire Markdown code as events and write them to a file
  help      Print this message or the help of the given subcommand(s)

Options:
  -y, --yes      Automatically answer `yes` to any user confirmation request
  -h, --help     Print help
  -V, --version  Print version

In turn, most commands offer a menu of subcommands.

Reference Definitions

mdbook-utils refdefs offers the following subcommands:

Manage reference definitions

Usage: mdbook-utils refdefs [OPTIONS] <COMMAND>

Commands:
  write     Write existing reference definitions to a file
  generate  Generate reference definitions (e.g. badges for Github links or from the dependencies of the code examples)
  help      Print this message or the help of the given subcommand(s)

Options:
  -y, --yes        Automatically answer `yes` to any user confirmation request
      --log <LOG>  Set the logging level (error, warn, info, debug, trace) [env: RUST_LOG=]
  -h, --help       Print help

Generate GitHub badges with the default flat Shields.io style:

mdbook-utils refdefs generate --badges --markdown-dir ./src --output ./badge_refs.md

Choose another supported style with --badge-style. The style option also enables badge generation, so --badges may be omitted:

mdbook-utils refdefs generate --badge-style flat-square --markdown-dir ./src --output ./badge_refs.md

Supported values are flat, flat-square, plastic, for-the-badge, and social. Omitting the option keeps the default flat output and leaves the style query parameter out of generated URLs.

Links

mdbook-utils links currently offers several subcommands:

Manage links

Usage: mdbook-utils links [OPTIONS] <COMMAND>

Commands:
  write-all        Write all existing links to a Markdown file
  write-inline     Write all existing inline / autolinks (i.e., not written as reference-style links) to a Markdown file
  duplicate-links  Identify links that repeat the same label, URL and title (inline links: the same URL) and write them to a Markdown file
  broken-links     Identify broken links (i.e. without reference definition) and write to a Markdown file
  help             Print this message or the help of the given subcommand(s)

Options:
  -y, --yes        Automatically answer `yes` to any user confirmation request
      --log <LOG>  Set the logging level (error, warn, info, debug, trace) [env: RUST_LOG=]
  -h, --help       Print help

links write-inline writes only inline links and autolinks that point to external http / https sites; relative paths, fragments, other schemes, and links inside code are excluded. Use --link-format <reference|inline|autolink> (default reference) to choose the output syntax. The autolink format drops link text and titles.

Link extraction follows CommonMark link syntax as implemented by pulldown-cmark, including inline links, reference links, images, and URI autolinks written in angle brackets. Plain URL text is not treated as an autolink. Link-like text in fenced or indented code blocks and code spans is preserved, as are mdBook helpers such as {{# include path/to/file.rs}}.

The parser enables the existing extensions for tables, footnotes, and strikethrough; it does not enable GitHub’s bare-URL autolinks or unrelated Markdown dialects. See the CommonMark specification for destination escaping and link syntax.

Generic website rules classify absolute http and https destinations. They separate query strings and fragments from the host and final path segment, preserve Unicode and percent-encoded text for matching, and reject destinations without a host or with raw whitespace. This is a parsing and classification boundary: mdBook-utils does not check whether a destination is reachable or validate every URI component. A destination accepted by CommonMark syntax may still contain a malformed percent escape and remains its original destination.

Markdown

mdbook-utils markdown deals with fenced code blocks and includes:

Manage code blocks (embedded examples) and includes

Usage: mdbook-utils markdown [OPTIONS] <COMMAND>

Commands:
  extract-code-examples              Copy Rust code examples from the Markdown into .rs files
  replace-code-examples-by-includes  Replace Rust code examples from the Markdown by {{#include ...}} statements
  replace-includes-by-contents       Replace {{#include file.md}} by the file contents
  remove-includes                    Remove {{#include }} statements (and replace them by a hard-coded string)
  generate-categories                Generate a listing of crates.io dependencies and write to a Markdown file
  generate-crates                    Generate a crate index and write to a Markdown file
  identify-files-not-in-summary      Identify .md files not in SUMMARY.md
  identify-unused-rs-examples        Identify .rs examples not used in Markdown files
  help                               Print this message or the help of the given subcommand(s)

Options:
  -y, --yes        Automatically answer `yes` to any user confirmation request
      --log <LOG>  Set the logging level (error, warn, info, debug, trace) [env: RUST_LOG=]
  -h, --help       Print help

To keep Rust examples in separate source files, run extract-code-examples with the Markdown source directory and an output directory. It writes each example under a directory derived from the chapter’s path, followed by block-NNN.rs. For example, chapters/intro.md maps to code/chapters/intro.md.d/block-000.rs. This keeps chapters with the same filename separate. Running extraction again is safe when the generated files still match; the command reports a conflict instead of overwriting an unrelated file.

After extraction, replace-code-examples-by-includes replaces the fenced Rust blocks with mdBook include directives that point to those files. Run replace-includes-by-contents to expand Markdown includes before a tool that does not process mdBook directives. Include paths resolve from the Markdown file containing each directive. The expansion command also handles mdBook line and named-anchor selectors, and leaves *-refs.md includes intact.

identify-files-not-in-summary reads chapter links from SUMMARY.md. Nested paths are resolved from the Markdown source directory, URL-encoded path characters are decoded, and query strings or heading fragments do not change which source file is checked, following mdBook’s SUMMARY.md chapter links. Links that resolve outside the source directory are ignored. A missing SUMMARY.md is an error.

identify-unused-rs-examples recognizes the mdBook Rust file helpers {{# include path/to/example.rs}}, {{# rustdoc_include path/to/example.rs:section}}, and {{# playground path/to/example.rs editable}}. Their paths are relative to the Markdown file containing the helper and must resolve inside the requested code directory. Other .rs text is not treated as a reference, including Rust string literals and ordinary prose or code that mentions a file path. Standard-library Rust macros such as include_str! are not interpreted by this Markdown scan.

These commands print the unmatched Markdown or Rust paths. A chapter omitted from SUMMARY.md appears in the first command’s output, and a Rust file with no supported mdBook helper appears in the second command’s output.

{{#include ../refs.md}}

mdbook-utils sitemap and mdbook-utils debug do not have subcommands.

Command-line options

Command-line options vary by subcommand and include -o to set the path of the output file; -m to set the path of the source Markdown directory (./src or ./drafts by default, depending on the subcommand); -c to set the path to the directory containing the Cargo.toml that declares the dependencies (Rust crates) used in your book; and -t to set the path to the destination directory.

-y is a global option that skips confirmation dialogs and is useful when calling mdbook-utils from a script. Commands that modify your Markdown files ask for confirmation first; without a terminal (for example in a script or CI) they fail with an error and change nothing unless -y is given.

--log <LEVEL> is a global option to set the logging level (error, warn, info, debug, trace). It trumps the RUST_LOG environment variable.

Use mdbook-utils <command> <subcommand> --help or help <command> <subcommand> for more details.

The following illustrates options for mdbook-utils sitemap:

Generate a sitemap.xml file from published HTML pages in SUMMARY.md

Usage: mdbook-utils sitemap [OPTIONS]

Options:
  -m, --markdown-dir <DIR>   Source directory containing the source Markdown files
  -b, --base-url <URL>       Base URL
  -o, --output <FILE>        Path of the file to create
      --map-index <FROM:TO>  Map a filename to another (e.g., 'intro.md' to 'index.md')
  -y, --yes                  Automatically answer `yes` to any user confirmation request
      --log <LOG>            Set the logging level (error, warn, info, debug, trace) [env: RUST_LOG=]
  -h, --help                 Print help

The sitemap destination must be inside an existing HTML renderer output directory, such as the configured mdBook build directory. A page is listed only when it appears in SUMMARY.md and its rendered HTML file exists in that output directory.

Which tool for what

mdbook-utils and book_tooling overlap. The split is:

mdbook-utils keeps pulldown-cmark for its read-only scans and does not rewrite link syntax in place. Commands that overlap with book_tooling (links write-inline, refdefs write) stay as reports and are not extended further.