MDBook LinkCheck

A backend for mdbook which will check your links for you. For use alongside the built-in HTML renderer.

Getting Started

First you'll need to install mdbook-linkcheck.

cargo install mdbook-linkcheck

If you don't want to install from source (which often takes a while) you can grab an executable from GitHub Releases or use this line of curl:

console curl -LSfs https://japaric.github.io/trust/install.sh | \ sh -s -- --git Michael-F-Bryan/mdbook-linkcheck

Next you'll need to update your book.toml to let mdbook know it needs to use the mdbook-linkcheck backend.

```toml [book] title = "My Awesome Book" authors = ["Michael-F-Bryan"]

[output.html]

[output.linkcheck] ```

And finally you should be able to run mdbook build like normal and everything should Just Work.

$ mdbook build

Note: When multiple [output] items are specified, mdbook tries to ensure that each [output] gets its own sub-directory within the build-dir (book/ by default).

That means if you go from only having the HTML renderer enabled to enabling both HTML and the linkchecker, your HTML will be placed in book/html/ instead of just book/ like before.

Configuration

The link checker's behaviour can be configured by setting options under the output.linkcheck table in your book.toml.

```toml ...

[output.linkcheck]

Should we check links on the internet? Enabling this option adds a

non-negligible performance impact

follow-web-links = false

Are we allowed to link to files outside of the book's root directory? This

may help prevent linking to sensitive files (e.g. "../../../../etc/shadow")

traverse-parent-directories = false

If necessary, you can exclude one or more web links from being checked with

a list of regular expressions

exclude = [ "google\.com" ]

The User-Agent to use when sending web requests

user-agent = "mdbook-linkcheck-0.4.0"

The number of seconds a cached result is valid for (12 hrs by default)

cache-timeout = 43200

How should warnings be treated?

#

- "warn" will emit warning messages

- "error" treats all warnings as errors, failing the linkcheck

- "ignore" will ignore warnings, suppressing diagnostic messages and allowing

the linkcheck to continuing

warning-policy = "warn"

Extra HTTP headers that must be send to certain web sites

in order to link check to succeed

#

This is a dictionary (map), with keys being regexes

matching a set of web sites, and values being an array of

the headers.

[http-headers]

Any hyperlink that contains this regexp will be sent

the "Accept: text/html" header

"crates.io" = ["Accept: text/html"]

mdbook-linkcheck will interpolate environment variables

into your header via $IDENT.

#

If this is not what you want

you must escape the $ symbol, like \$TOKEN. \ itself can also be escaped

via \\.

"website.com" = ["Authorization: Basic $TOKEN"] ```

Continuous Integration

Incorporating mdbook-linkcheck into your CI system should be straightforward if you are already using mdbook to generate documentation.

For those using GitLab's built-in CI:

``yaml book: stage: build image : rust:latest variables: # makes sure the~/.cargo` directory gets cached too CARGOHOME: $CIPROJECTDIR/cargo beforescript: - rustc --version --verbose && cargo --version --verbose - export PATH=$CARGOHOME/bin:$PATH # Install mdbook and mdbook-linkcheck without optimisations, if not # already installed - command -v mdbook >/dev/null 2>&1 || cargo install --debug mdbook - command -v mdbook-linkcheck >/dev/null 2>&1 || cargo install --debug mdbook-linkcheck script: - mdbook build artifacts: paths: - book

pages: image: busybox:latest stage: deploy dependencies: - book script: - mkdir -p public - cp -r book public artifacts: paths: - public only: - master ```

@danieltrautmann has also created a docker image that comes with mdbook and mdbook-linkcheck pre-installed.