Steve Martinelli

3 minute read

Banner image by rawpixel.com and freepik.com

Recently, I spent a few days experimenting with Material for MkDocs. In short, I’m impressed with the project and hope it continues to gain traction. It does, as the project tag line suggests…

Technical documentation that just works.

In this blog post, in no particular order, are five things I like about the Material for MkDocs project.

If you’re interested in seeing what I built using Material for MkDocs, check out https://stevemar.github.io/minimal-workshop-mkdocs/.

About Material for MkDocs

If you’re not familiar with Material for MkDocs, it’s one of many options to host your open source technical documentation. If you’re familiar with GitBook, it’s like that. It, like most other projects with similar goals, relies on the documentation being written in Markdown.

It has wonderful documentation, a very well maintained and active repo, and boasts an impressive list of users, like AWS or Kubernetes

1. Fantastic looking graphical

The first thing I’ll mention is that Material for MkDocs supports a variety of markdown plugins out of the box, enabling it to have some great user interfaces for your static site. Here are my three favorites:

Admonitions

Admonitions are available and come with 12 different display settings. Depending on what label you use in your admonition you get a particular color and icon.

call outs

Tabbed content

Another feature I like is that you can display tabbed content on your page. For instance, if you had some commands that a user should run depending on an operating system (Windows, Linux, or Mac), this would work perfectly.

tabs

Buttons

This probably shouldn’t be a big deal, but adding a simple button to a static site is usually one of those steps that is harder than it should be. With Material for MkDocs it’s very simple.

buttons

2. Social media footers

The next neat feature lies in the footer. Adding all affiliated social media accounts is very easy and done in minutes.

media

A full list of supported brands are in the project repo.

3. GitHub Actions integration

I’m a fan of GitHub Actions (see my previous posts “Removing unused images” and “Deploying to IBM Cloud Kubernetes”). So seeing that Material for MkDocs deplyed to GitHub pages via GitHub Actions got me excited. You just need to drop this code in the usual .github/workflows path. Turn on GitHub Pages to deploy from the gh-pages branch, and you’re live!

name: ci
on:
  push:
    branches:
      - main
      - master
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
        with:
          python-version: 3.x
      - run: pip install mkdocs-material
      - run: mkdocs gh-deploy --force

4. Easy to set up

Material for MkDocs says “get up and running in 5 minutes”. And yeah, I can say that the statement is accurate.

Install the package;

pip install mkdocs-material

Place a config file mkdocs.yml in the top level directory. Minimally, you need the contents below. And put all your markdown files in a docs folder.

theme:
  name: material

Run and test the site locally with:

mkdocs serve

5. All goverened by a single file

As long as you don’t extend the base theme, the site’s style and layout are basically governed by a single file. Which, if you’re controlling multiple repositories and looking for consistency, makes things much more manageable.

Here’s a snippet of what I use, check out my complete config file over here:

# Theme
theme:
  name: material
  features:
    - navigation.tabs

# Project information
site_name: Minimal Workshop
site_url: https://stevemar.github.io/minimal-workshop-mkdocs
site_author: IBM Developer

# Repository
repo_name: minimal-workshop-mkdocs
repo_url: https://github.com/stevemar/minimal-workshop-mkdocs

# Navigation
nav:
  - Welcome:
    - About the site: index.md
  - Workshop:
    - Lab 1: workshop/lab-1.md
    - Lab 2: workshop/lab-2.md
    - Lab 3: workshop/lab-3.md

Final thoughts

Material for MkDocs is a great project. It’s maintainer, Martin Donath, is passionate about the project and is basically its sole maintainer. The project is entirely open source but does use the sponsorware release strategy, meaning new features are first exclusively released to sponsors.

I had other colleagues as why not use Docusaurus? And as much as I like that Docusaurus provides even more flexibility, there’s something that bugs me about using React for a static site.

Updated:

You May Also Enjoy