Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/Michael-F-Bryan/mdbook-linkcheck

A backend for `mdbook` which will check your links for you.
https://github.com/Michael-F-Bryan/mdbook-linkcheck

Last synced: 9 days ago
JSON representation

A backend for `mdbook` which will check your links for you.

Awesome Lists containing this project

README 

        
# MDBook Link-Check



[![Continuous integration](https://github.com/Michael-F-Bryan/mdbook-linkcheck/workflows/Continuous%20integration/badge.svg?branch=master)](https://github.com/Michael-F-Bryan/mdbook-linkcheck/actions)

[![Crates.io](https://img.shields.io/crates/v/mdbook-linkcheck.svg)](https://crates.io/crates/mdbook-linkcheck)

[![Docs.rs](https://docs.rs/mdbook-linkcheck/badge.svg)](https://docs.rs/mdbook-linkcheck/)

[![license](https://img.shields.io/github/license/michael-f-bryan/mdbook-linkcheck.svg)](https://github.com/Michael-F-Bryan/mdbook-linkcheck/blob/master/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][releases] or use this line of

`curl` to download a release bundle and install it in the `./mdbook-linkcheck`

directory:



```console

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.



```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 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.

[output.linkcheck.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 `\\`.

#

# 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][mdbook-ci].



For those using GitLab's built-in CI:



```yaml

generate-book:

  stage: build

  image:

    name: michaelfbryan/mdbook-docker-image:latest

    entrypoint: [""]

  script:

    - mdbook build $BOOK_DIR

  artifacts:

    paths:

      - $BOOK_DIR/book/html

    # make sure GitLab doesn't accidentally keep every book you ever generate

    # indefinitely

    expire_in: 1 week



pages:

  image: busybox:latest

  stage: deploy

  dependencies:

    - generate-book

  script:

    - cp -r $BOOK_DIR/book/html public

  artifacts:

    paths:

    - public

  only:

    - master

```



The [michaelfbryan/mdbook-docker-image][image] docker image is also available

on Docker hub and comes with the latest version of `mdbook` and

`mdbook-linkcheck` pre-installed.



[releases]: https://github.com/Michael-F-Bryan/mdbook-linkcheck/releases

[mdbook-ci]: https://rust-lang.github.io/mdBook/continuous-integration.html

[Michael-F-Bryan]: https://github.com/Michael-F-Bryan

[image]: https://hub.docker.com/r/michaelfbryan/mdbook-docker-image