5 Features I Like About Material for MkDocs
Published: 2020-11-28 06:46:02

Recently, I spent a few days experimenting with [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/). 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](https://squidfunk.github.io/mkdocs-material/), a very well maintained and [active repo](https://github.com/squidfunk/mkdocs-material), and boasts an impressive list of users, like [AWS](https://aws.github.io/copilot-cli/) or [Kubernetes](https://kops.sigs.k8s.io/)

## 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.

![admonitions](https://dev-to-uploads.s3.amazonaws.com/i/xigqedhv38wlyggb3354.png)

### 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](https://dev-to-uploads.s3.amazonaws.com/i/r3sgb4vym2nq5h0y0945.png)

### 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](https://dev-to-uploads.s3.amazonaws.com/i/637f36rwswkweyl51mgx.png)

## 2. Social media footers

The next neat feature lies in the footer. Adding all brand icons is very easy and done in minutes.

![social](https://dev-to-uploads.s3.amazonaws.com/i/aatmxn5u0h9h1ipwlgds.png)

A full list of supported brand icons is in the project [repo](https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons/fontawesome/brands).

## 3. GitHub Actions integration

I'm a fan of GitHub Actions (see my previous posts ["Removing unused images"](https://www.stevemar.net/github-actions-rm-images/) and ["Deploying to IBM Cloud Kubernetes"](https://www.stevemar.net/github-actions-with-iks/)). 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!

```yaml
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;

```bash
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.

```yaml
theme:
  name: material
```

Run and test the site locally with:

```bash
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 is 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](https://github.com/stevemar/minimal-workshop-mkdocs/blob/main/mkdocs.yml):

```yaml
# 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](https://github.com/squidfunk), is passionate about the project and is basically it's sole maintainer. The project is entirely open source but does use the [sponsorware](https://github.com/sponsorware/docs) release strategy, meaning new features are first exclusively released to sponsors. If you're interested I encourage you to check it out.