Configuration

This page lists all options for the preprocessor.

For use in book.toml, configure under the [preprocessor.link-forever] table using the keys below, for example:

[preprocessor.link-forever]
always-link = [".rs"]

always-link

Convert some paths to permalinks even if they are under src/.

By default, links to files in your book's src/ directory will not be transformed, since they are already copied to build output as static files. If you want such files to always be rendered as permalinks, specify their file extensions here.

For example, to use permalinks for Rust source files even if they are in the book's src/ directory:

always-link = [".rs"]

book-url

Specify the canonical URL at which you deploy your book.

Should be a qualified URL. For example:

book-url = "https://me.github.io/my-awesome-crate/"

Enables validation of hard-coded links to book pages. The preprocessor will warn you about links that are no longer valid (file not found) at build time.

This is mainly used with mdBook's {{#include}} feature, where sometimes you have to specify full URLs because path-based links are not supported.

fail-on-warnings

Exit with a non-zero status code when there are warnings.

Warnings are always printed to the console regardless of this option.

repo-url-template

Use a custom link format for platforms other than GitHub.

Should be a string that contains the following placeholders that will be filled in at build time:

• {ref} — the Git reference (tag or commit ID) resolved at build time
• {path} — path to the linked file relative to repo root, without a leading /

For example, the following configures generated links to use GitLab's format:

repo-url-template = "https://gitlab.haskell.org/ghc/ghc/-/tree/{ref}/{path}"

Note that information such as repo owner or name will not be filled in. If URLs to your Git hosting service require such items, you should hard-code them in the pattern.