Features

Simply use relative paths to link to any file in your source tree, and the preprocessor will convert them to GitHub permalinks.

This project is dual licensed under the
[Apache License, Version 2.0](../../../LICENSE-APACHE.md) and the
[MIT (Expat) License](../../../LICENSE-MIT.md).

This project is dual licensed under the Apache License, Version 2.0 and the MIT (Expat) License.

Permalinks use the tag name or commit SHA of HEAD at build time, so you get a rendered book with intra-repo links that are always correct for that point in time.

tip

Linking by path is cool! Not only is it well-supported by GitHub, but editors like VS Code also provide smart features like path completions and link validation.

URL fragments are preserved:

This book uses [esbuild] to
[preprocess its style sheet](../../app/build/build.ts#L13-L24).

This book uses esbuild to preprocess its style sheet.

By default, links to files under your book's src/ directory are not converted, since mdBook already copies them to build output, but this is configurable using the always-link option.

Repo auto-discovery

To know what GitHub repository to link to, the preprocessor looks at the following places, in order:

  1. The output.html.git-repository-url option in your book.toml
  2. The URL of a Git remote named origin1

tip

For Git remotes, both HTTP URLs and "scp-like" URIs (git@github.com:org/repo.git) are supported, thanks to the gix_url crate.

If you use Git but not GitHub, you can configure a custom URL pattern using the repo-url-template option. For example:

[preprocessor.link-forever]
repo-url-template = "https://gitlab.haskell.org/ghc/ghc/-/tree/{ref}/{path}"

The preprocessor validates any path-based links and notifies you if they are broken.

warnings emitted for broken links

Formatting of diagnostics powered by miette

note

Link validations are only supported for path-based links. For more comprehensive link checking, look to projects like mdbook-linkcheck.

  1. The remote must be exactly named origin. No other name is recognized. ↩