mdbook-force-relative-links, an mdbook pre-processor

This repository contains the source for the mdbook-force-relative-links pre-processor, which will transform all absolute links in a book to a relative form resolving to the same file.

mdbook is a tool to produce books from Markdown files.

Pre-processors are programs that modifies or check a book before is it given to the renderer (to produce HTML, a PDF, an EPUB, ...), allowing for arbitrary transformations of the resolved Markdown.

Usage

Add the following to your book.toml:

[prepocessor.force-relative-links]
after = ["links"] # Required to resolve links that comes from `{{#include}}` directives

And mdbook-force-relative-links needs to be in PATH when mdbook is called.

Why ?

It is not rare for a book to be hosted under a subpath of the root, for example GitHub pages deploys to <org>.github.io/<project>/<pages>, so any absolute link in a book hosted there will resolve to <org>.github.io and not the actual root.

Most of the time, this is not an issue, but it can easily become one when including the same file in several places that are not at the same depth (in terms of path): in that case it is not possible to write the link to correctly resolve in all cases with only mdbook.

License

All the code in this repository is released under the Mozilla Public License v2.0, for more information take a look at the [LICENSE] file.