mdBook with absolute links via site-url

mdBook is a utility to create modern online books from Markdown files.

Code here is a fix for Absolute Links with site-url value setting in book.toml config.

This fix version has been reported to mdBook source as comment to issue 10802

Check out the User Guide for a list of features and installation and usage information. The User Guide also serves as a demonstration to showcase what a book looks like.

If you are interested in contributing to the development of mdBook, check out the Contribution Guide.

How to use it

mdBook has to be build and optionally installed

Try sitefix-book as book example using /doc/ as site-url
or use full absolute URL complete with hostnames and schemas ends with / for example: http://localhost:3000/doc/

In sitefix-book/book.toml add base_url (base href) to rendered files with site-url value, ends with /

In case relative path in TOC and SUMMARY is not fixed with site-url value:

• Replace SUMMARY.md entries to include site-url
• Replace TOC entries for each sidebar chapter-item to include site-url

see example below

To complement this fix:

• mdBook Tera preprocessor should be added (installed) and activated in book.toml
• context.toml for mdBook Tera preprocessor has to include urlbase with same site-url value
• Markdown URLS or SRC in book files has to start with {{urlbase}} prefix

[Introduction]({{urlbase}}introduction.md)
![Image]({{urlbase}}image.jpg)

my-theme/index.hbs is used to set urlbase in previous and next navigation

You can use a script to automate builds:

• Take care of: paths, book.toml, index.hbs, etc.
• Use mdBook to build rendered result to dist path rather than default book

if not installed add build target path to mdbook (../target/debug/)

mkdir -p /tmp/site/doc
mdbook build --dest-dir /tmp/site/doc

IMPORTANT: site-url only works with mdbook build with serve option has no sense as it is for development and site-url is overwritten with local path.

By using these procedures sitefix-book distribution build can be tested with

cd /tmp/site/doc
python3 -m http.server

Use a web-browser for: http://localhost:3000/doc

For distribution or publish mdBooks follow above instructions or use a script to set absolute_path in book.toml and context.toml

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.