Guides for MkDocs documentation sites

A collection of guides on topics relating to MkDocs and the Material theme.
Published

December 21, 2021

Modified

May 31, 2025

These guides are deprecated. I’m no longer updating them. This is due to developments in the MkDocs ecosystem: the maintainer of MkDocs is taking it in a new direction, and the creator of the Material theme is building his own static site generator, Zensical.

Learn more:

The Slow Collapse of MkDocs
Zensical

This section contains guides around MkDocs with the Material theme. This is my favourite docs tooling.

Background on the deployment guides

I’ve tested out a range of hosting and CI (continuous integration) providers for docs like code setups. This section includes deployment guides for my recommended options. I currently use Cloudflare Pages for my own sites.

Requirements

A docs like code setup usually involves:

  • Documents written in a markup language (such as Markdown or AsciiDoc)
  • A static site generator to build the website
  • Source files stored under version control
  • Ideally, automated testing and deployments

For any website project I have a few key requirements:

  • Automated deploys on merge to main
  • Automated preview builds on pull request
  • Simple setup (“simple” is subjective, of course)
  • A way to redirect pages to new URLs

For docs projects, I’d add:

  • Automated linting (running Vale, and a link checker on pull request).
  • Ability to encrypt build environment variables (using Material Insiders requires a GitHub access token, which I don’t want to leave exposed in site settings).
  • Reasonable pricing for a large number of contributors.
  • Really simple setup: I want to be able to recommend this tooling to clients, without relying on them having devops resources available for their docs work.

And some nice-to-haves:

  • A free tier (for testing and hobby projects at least)
  • Easy domain and SSL setup

There are a few things I’m not looking for that you might want to consider:

  • Access control (if you need your docs and/or preview builds behind a login).
  • Analytics (I’m happy using Plausible, but some hosting providers offer built in options, which are convenient).
  • Support for git providers other than GitHub.