#mdbook #check #link #back-end #book #directory #linkcheck

bin+lib mdbook-linkcheck

A backend for mdbook which will check your links for you

22 releases

0.7.7 Oct 3, 2022
0.7.6 Nov 12, 2021
0.7.5 Sep 6, 2021
0.7.4 Feb 26, 2021
0.1.2 Mar 15, 2018

#201 in Text processing

Download history 997/week @ 2024-01-12 1023/week @ 2024-01-19 1468/week @ 2024-01-26 1553/week @ 2024-02-02 1093/week @ 2024-02-09 1171/week @ 2024-02-16 1228/week @ 2024-02-23 1202/week @ 2024-03-01 1173/week @ 2024-03-08 1538/week @ 2024-03-15 1152/week @ 2024-03-22 907/week @ 2024-03-29 1340/week @ 2024-04-05 1283/week @ 2024-04-12 1247/week @ 2024-04-19 895/week @ 2024-04-26

4,980 downloads per month

MIT license


MDBook Link-Check

Continuous integration Crates.io Docs.rs license

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 to download a release bundle and install it in the ./mdbook-linkcheck directory:

mkdir -p mdbook-linkcheck && cd "$_" && \
  curl -L https://github.com/Michael-F-Bryan/mdbook-linkcheck/releases/latest/download/mdbook-linkcheck.x86_64-unknown-linux-gnu.zip -o mdbook-linkcheck.zip && \
  unzip "$_" && \
  chmod +x mdbook-linkcheck && \
  export PATH=$PWD:$PATH && \
  cd ..

(note: you may need to replace the x86_64-unknown-linux-gnu with your platform's target triple)

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

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



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.


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


# 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 links from being checked with a
# list of regular expressions. The regex will be applied to the link href (i.e.
# the `./index.html` in `[some page](./index.html)`) so it can be used to
# ignore both web and filesystem links.
# Hint: you can use TOML's raw strings (single quote) to avoid needing to
# escape things twice.
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.
# 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
# If this is not what you want you must escape the `$` symbol, like `\$TOKEN`.
# `\` itself can also be escaped via `\\`.
# Note: If interpolation fails, the header will be skipped and the failure will
# be logged. This can be useful if a particular header isn't always necessary,
# but may be helpful (e.g. when working with rate limiting).
'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:

  stage: build
    name: michaelfbryan/mdbook-docker-image:latest
    entrypoint: [""]
    - mdbook build $BOOK_DIR
      - $BOOK_DIR/book/html
    # make sure GitLab doesn't accidentally keep every book you ever generate
    # indefinitely
    expire_in: 1 week

  image: busybox:latest
  stage: deploy
    - generate-book
    - cp -r $BOOK_DIR/book/html public
    - public
    - master

The michaelfbryan/mdbook-docker-image docker image is also available on Docker hub and comes with the latest version of mdbook and mdbook-linkcheck pre-installed.


~567K SLoC