Skip to main content

Deploying mdBook site on Netlify

29 Jul 2020 · Last updated: 31 Jul 2020 ·
Posted in weblog#tech

Now that I've got a domain, I have moved my project sites from GitHub Pages to Netlify, and serve them from subdomains right from Netlify using Netlify DNS. This is technically possible for sites hosted on GitHub Pages. You need to add a CNAME record to your DNS provider and CNAME file at the root of your project repository. Refer to GitHub's documentation for details.

This is a simple enough task but I came across some quirks and information that might be useful:

  • One of my sites is built using mdBook, a static site generator written in Rust but Netlify doesn't support Rust in its build image like Node, Python or Ruby. If you use mdbook build as build command, you'll get mdbook : command not found error in deploy log.

To solve this problem, use the following build command:

curl -L https://github.com/rust-lang/mdBook/releases/download/v0.3.7/mdbook-v0.3.7-x86_64-unknown-linux-gnu.tar.gz | tar xvz && ./mdbook build

Make sure to change the version to the one that you want to use.

  • mdBook puts generated HTML and CSS files in the book directory (like build dir used by npm) by default. So, use this dir (or whatever folder you have used in the configuration) as publish directory.

  • I had problems with pages generated from LICENSE and CONTRIBUTING.md files. These files are located at the root directory of the project. I had to disable Netlify's Pretty URLs (Settings > Build & deploy > Post processing > Asset optimization) to make this work.

  • I couldn't get sidebar to resize. Disabling Bundle CSS on Netlify worked. This might not be necessary if using v0.4.