Skip to content

Technical writing with material for mkdocs

Abstract

Material for mkdocs is a documentation framework adopted by many popular python libraries e.g. this, this and this. The plugins and markdown extensions make writing rich technical content delightful e.g. maths, code, docstring parsers, and more. The main apeal of the project is that "it's just markdown" (with a bit of extended syntax). This tutorial provides a step by step intro to setting up a blog website (such as this one!) with this framework.

Credit

template by material team

First steps to follow

  1. pip install mkdocs-material
  2. initialize docs locally with mkdocs new .
  3. create empty remote repo and push local to remote
  4. [github] add CI config file as per material docs
  5. [github] set publish branch to gh-pages

After these steps, a site is published and CI should start working. New edits of docs in the main branch would trigger rebuild of the site, i.e. focus on the writing and let robots build the site automatically.

Customize the theme

In mkdocs.yml, config the theme, then customize it e.g. add dark/light toggle

Add blog plugin

Without any setting, the plugin creates a directory structure (/docs/blog/posts).

Setting the following should be straightforward

  1. blog_toc
  2. archive_date_format
  3. categories_allowed
  4. pagination_per_page

The post_slugify setting makes use of python markdown extension package, which is a dependency of material and installed with it.

Add tags plugin

Add tags plugin in mkdocs.yml and create a file tags.md in docs.

Add rss plugin

rss is a third party plugin which requires installation.

It is important that have the site_name, site_description and site_url settings configured. The RSS plugin makes use of this information to construct the feed, so make sure you have configured them.

  • pip install mkdocs-rss-plugin
  • add rss plugin in mkdocs.yml
  • add the required package also in ci: run pip install mkdocs-rss-plugin

Extra

such as social media links in the footer

Markdown extension: maths

Add markdown extension for writing maths

  • add arithmatex extension in mkdocs.yml
  • add mathjax.js to extra_javascript (create a js file in docs/js, define macros as needed)

One can use katex instead per documentation.

Markdown extension: code block

Add necessary markdown extension for writing code.

  • highlight
  • inlinehilite
  • snippets
  • superfences

Rename nav sidebar and/or turn it into tabs.

Add to features in theme

  • navigation.tabs : tabs
  • navigation.indexes : index attached to sections (overview page)

Also add nav section to be explicit what to include in the sidebar/tabs.

Author

Add author metadata docs/blog/.author.yml and use it in all posts (by specifying authors in the header of posts).

Metadata of posts

Include metadata in the header of posts:

  • date (enough)
  • authors
  • tags
  • categories
  • slug (if want to customize)
  • readtime