Skip to content

Create better documentation with Mkdocs

3 min read
SetupCustomizationsDark mode & colorsAdmonitionsBuilding

I'm a big proponent of creating documentation because it not only helps me remember how to use things I've built months later, but it also reduces the friction often present for other members trying to learn how to use and maintain your code.

MkDocs has become my go-to tool for static docs because I can:

  • Maintain all my docs in Markdown
  • Don't need to write any code
  • Can easily deploy the documentation to a static host like Cloudflare Pages or Netlify
  • Can be easily protected with Cloudflare Zero trust
  • Looks pretty

Setup

Before getting started, let's create a blank documentation directory.

I like to use virtualenv to isolate all my Python dependencies so I don't clobber any locally installed things.

virtualenv venv
source venv/bin/activate

# Verify Python installation directory
which python3
/Users/schachte/Documents/Programming/Homelab/venv/bin/python3

Anything installed via pip moving forward will be located in the venv directory.

# documentation engine
pip3 install mkdocs

# pretty theme
pip3 install mkdocs-material

We'll be using Mkdocs Material as our base theme as it looks really good and is a piece of cake to setup.

If you end up installing a bunch of plugins for mkdocs, I recommend versioning your dependencies with something like pip freeze > requirements.txt. If you need to run the setup on another machine, you can simply automate the installation with pip install -r requirements.txt and your virtualenv will be ready to go!

documentation
├── docs
│   └── index.md
├── mkdocs.yml
└── requirements.txt

To enable the theme, open up mkdocs.yml in your docs directory and add the following:

site_name: Homelab Documentation
theme:
  name: material

You should now be able to view the docs at https://localhost:8080 by running mkdocs serve:

mkdocs serve
INFO    -  Building documentation...
INFO    -  Cleaning site directory
INFO    -  Documentation built in 0.16 seconds
INFO    -  [13:28:32] Watching paths for changes: 'docs', 'mkdocs.yml'
INFO    -  [13:28:32] Serving on http://127.0.0.1:8000/

Customizations

There are a ton of customizations you can add to your site. I'll touch on a couple I really enjoy.

Dark mode & colors

You can view loads of colors for mkdocs-material here, but I just want the classic dark mode since it's sleek and easy on the eyes.

Fortunately, this is built-in and just requires a slight modification to the mkdocs.yml file to specify the slate theme.

site_name: Homelab Documentation
theme:
  name: material
  palette:
    scheme: slate

admonition example

Beautiful 👌.

Admonitions

Admonitions are great because they give a nice aesthetic for call-to-actions in your docs like warnings or informational banners.

When writing docs with Mkdocs, you can simply write something like:

!!! note
    Welcome to my awesome note

and get the following:

admonition example

Add the following to mkdocs.yml

site_name: Homelab Documentation
theme:
  name: material
  palette:
    scheme: slate
markdown_extensions:
  - admonition
  - pymdownx.details
  - pymdownx.superfences

Building

To ensure we don't suffix our URLs incorrectly, I'm going to slightly adjust the mkdocs.yml file like so:

site_name: Homelab Documentation
site_url: ''
use_directory_urls: false
theme:
  name: material
  palette:
    scheme: slate
markdown_extensions:
  - admonition
  - pymdownx.details
  - pymdownx.superfences

If the built site will not be behind a server, then you may set the value for site_url to an empty string (''). When set to an empty string, some features of MkDocs may act differently. For example, the use_directory_urls setting must be set to false. The site_url is the canonical URL of the server and you're welcome to set this to your domain as well.

You can build your site statically and view what the build looks like locally very easily.

  1. Navigate to the directory where mkdocs.yml is
  2. Run mkdocs build
  3. Serve the build with http-server by running http-server site/ and navigating to localhost:8080

Once you confirm everything looks good, create a repo on something like Github and commit the files.