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.
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 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.
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.
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.
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.
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
theme: name: material
Run and test the site locally with:
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
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.