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/.
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.
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.
The next neat feature lies in the footer. Adding all brand icons is very easy and done in minutes.
A full list of supported brand icons is in the project repo.
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
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:
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:
# 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 it's sole maintainer. The project is entirely open source but does use the sponsorware release strategy, meaning new features are first exclusively released to sponsors. If you're interested I encourage you to check it out.