Creating your own mdBook-based Knowledge Repository

The short version of this page.

I maintain a second knowledge repository for work-specific things, these are the instructions I used for setting that one up.

Machine Setup

mdBook requires rust to use, so we first install rust. This is done via rustup.

  • curl --proto '=https' --tlsv1.2 -sSf | sh

Next, we install mdbook itself: cargo install mdbook.

Optionally, we can install my mdbook-generate-summary tool, which means we don’t have to maintain the file that mdbook requires. If you don’t want to install that, then you also need to add an entry to the file each time you create or move files around.

  • cargo install mdbook-generate-summary

This is all that’s required to setup the machine.

Setting up the Repository

To set up the repository itself, you need to create a book.toml file, an initial src/ file, and (if not using mdbook-generate-summary) a src/ file.

For reference, this repository’s book.toml file is:

title = "Knowledge Repository"
authors = ["Rachel Brindle"]
description = "Rachel's Digital Garden"

preprocess = ["links", "index"]

curly-quotes = true
no-section-label = true
mathjax-support = true
additional-css = ["css/custom.css"]
git-repository-url = ""
edit-url-template = "{path}"


hide_invalid = false
invalid_message = "🚨 Warning, this content is out of date and is included for historical reasons."

strict = true

base_url = ""
article_preview_lines = 10

The only special thing is that this repository also uses my mdbook-api backend, in order to export things for use with my client side tooling.

Building the Repository

If you want to view the repository locally, you can use mdbook build, and open book/index.html in your web browser. If you’re doing interactive work, then you can use mdbook watch.

Note that if you’re using mdbook-generate-summary, you should run that every time you create, delete, or move a page.

Last updated: 2019-07-08 14:46:09 -0700