Skip to content

Documentation with Material for MkDocs

Learning Objectives

By the end of this section, you should be able to:

  • Explain why Material for MkDocs is an optimal choice to build your documentation
  • Know how to navigate the official documentation of Material for MkDocs
  • Build your own documentation from scratch
  • Explain how the quizli documentation was built

What is Material for MkDocs?

Material for MkDocs is a Material Design theme for MkDocs.

Info

Material

A design system created by Google to help teams build high-quality digital experiences for Android, iOS, Flutter, and the web.

MkDocs

A fast, simple and downright gorgeous static site generator that's geared towards building project documentation. Documentation source files are written in Markdown, and configured with a single YAML configuration file.

With Material for MkDocs you can, quoting it's Github Readme, create

a branded static site from a set of Markdown files to host the documentation of your Open Source or commercial project - customizable, searchable, mobile-friendly, 50+ languages. Set up in 5 minutes.

Alternative themes

If you don't like the look of the Material theme, there is a list of alternative MkDocs themes

Why Material for MkDocs?

Here is a list of features that make Material for MkDocs a great choice:

  1. Geared towards (technical) project documentation
  2. Future-proof & simple to use thanks to using Markdown source
  3. Generates a SEO-friendly site
  4. It's Open-Source & has a permissive license (MIT)
  5. It's customizable (via JavaScript and CSS) and extendable (via plugins)
  6. Easy to publish via Gitlab/Github Pages

Alternative static site generators

Read the following section in Material for MkDocs' documentation to see how it compares to alternative static site generators: Alternatives

To prove to you how easy it is to generate a basic documentation for your existing project, we point to the following example:

Example

Minimal Example

  1. Install Material for MkDocs with: 
    pip install mkdocs-material
  2. Move your existing Markdown files into a docs/ folder
  3. Add a mkdocs.yml file in your project root with the minimal content:
theme:
  name: material

Hint

For new projects steps 2. and 3. can be even abbreviated further with the mkdocs new . command

🚀 That's all you need. Just serve your docs with mkdocs serve and enjoy them in your browser.

Amazingly, for many projects this simple setup already leads to a great documentation since Material for MkDocs uses reasonable defaults.

Still, there is plenty room for improvement. So in the following subsections we walk you through some customizations to build a more sophisticated documentation.

How to Create your own Documentation from Scratch?

Instead of (doing a bad job in) rewriting the existing documentation of Material for MkDocs, we will instead point out and guide you through the relevant sections.

1. The Getting Started Section

If you are new to Material for MkDocs, first check out its Getting Started section. It contains installation instructions, an example of how to create a minimal documentation, and a few brief discussions of more advanced topics like publishing your documentation. At the end of it, you should already be equipped with a bare-bones documentation.

2. The Setup Section

Next, I suggest you read through the setup section in order to add more features to your documentation and to customize it.

Info

Below you can see all customization options that currently exist.

I added a checkmark for those options that are used by quizli.

  • Changing the colors
  • Changing the fonts
  • Changing the language
  • Changing the logo and icons
  • Setting up navigation
  • Setting up site search
  • Setting up site analytics
  • Setting up social cards
  • Setting up tags
  • Setting up versioning
  • Setting up the header
  • Setting up the footer
  • Adding a git repository
  • Adding a comment system

3. The Reference Section

I bet at this point your documentation looks quite amazing already, but we can improve it even more by leveraging the reference section.

Info

As of time of writing, the reference section comprises the following parts.

Again we add checkmarks for those features that we used for quizli's docs.

  • Abbreviations
  • Admonitions
  • Annotations
  • Buttons
  • Code blocks
  • Content tabs
  • Data tables
  • Diagrams
  • Footnotes
  • Formatting
  • Icons + Emojis
  • Images
  • Lists
  • MathJax

Learning by Example: quizli

I encourage you to browse through quizli's documentation and whenever you see something you like, or you are curious of how things are done, take a look at the corresponding sections in the docs folder.

Tip: Learning by Example

Many popular projects use Material for MkDocs.

Their creators are often experienced and creative developers who put a lot of effort into their documentation.

Hence a great way to learn is to read through their documentation and see what you can adapt.

Some examples:

And plenty more!

Configuring the documentation

Below you find the configuration settings of quizli's documentation.

For each block of settings, I added a link to the corresponding section in the Material for MkDocs documentation for further reference.

The configuration file: mkdocs.yml
---
#  ╭──────────────────────────────────────────────────────────╮
#  │                  Adding site information                 │
#  ╰──────────────────────────────────────────────────────────╯

site_name: quizli
site_url: https://pwenker.github.io/quizli
site_description: An educational project teaching how to create an open-source Python package with the example of an interactive quiz app

#  ╭──────────────────────────────────────────────────────────╮
#  │                  Adding a git repository                 │
#  ╰──────────────────────────────────────────────────────────╯
# See: https://squidfunk.github.io/mkdocs-material/setup/adding-a-git-repository/

repo_url: https://github.com/pwenker/quizli
repo_name: pwenker/quizli
edit_uri: edit/master/docs/

docs_dir: docs
use_directory_urls: false

#  ╭──────────────────────────────────────────────────────────╮
#  │                   Setting up the footer                  │
#  ╰──────────────────────────────────────────────────────────╯
# See: https://squidfunk.github.io/mkdocs-material/setup/setting-up-the-footer/

extra:
  social:
  - icon: fontawesome/brands/github
    link: "https://www.github.com/pwenker"
  - icon: fontawesome/brands/twitter
    link: "https://www.twitter.com/PascalWenker"
  - icon: fontawesome/brands/linkedin
    link: "https://www.linkedin.com/in/pascal-wenker-25a568125/"
  - icon: fontawesome/brands/youtube
    link: "https://www.youtube.com/channel/UCYxDcdFLW-AMoHEfh7pG-oA"
  disqus: "www-pwenker-com" 

copyright: Copyright © 2021 - 2022 Pascal Wenker

#  ╭──────────────────────────────────────────────────────────╮
#  │                Setting up the colorscheme                │
#  ╰──────────────────────────────────────────────────────────╯
# Here we set the color scheme and also enable toggling between a light and a dark mode.
# See: https://squidfunk.github.io/mkdocs-material/setup/changing-the-colors/

theme:
  name: material
  palette:
    - scheme: default
      toggle:
        icon: material/weather-night
        name: Switch to dark mode
    - scheme: slate
      toggle:
        icon: material/weather-sunny
        name: Switch to light mode

  icon:
    #  ╭──────────────────────────────────────────────────────────╮
    #  │                Changing the logo and icons               │
    #  ╰──────────────────────────────────────────────────────────╯
    # See : https://squidfunk.github.io/mkdocs-material/setup/changing-the-logo-and-icons/
    logo: material/head-question-outline
    # See: https://squidfunk.github.io/mkdocs-material/setup/adding-a-git-repository/
    repo: fontawesome/brands/github
  # See: https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/
  features:
    - navigation.tabs
    - navigation.indexes

  # Uncomment the line below to prevent typefaces from being loaded from Google Fonts
  # See: https://squidfunk.github.io/mkdocs-material/setup/changing-the-fonts/#autoloading
  # font: false


#  ╭──────────────────────────────────────────────────────────╮
#  │                   Setup MkDocs Plugins                   │
#  ╰──────────────────────────────────────────────────────────╯
# See: https://www.mkdocs.org/dev-guide/plugins/
plugins:
    # The built-in search plugin (https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-search/) 
    - search 
    - mkdocs-jupyter:
        include_source: false
        execute: false
    - mkdocstrings: # This is used to generate documentation of source code
           handlers:
               python:
                   setup_commands:
                       - import sys
                       - sys.path.append('../')
                   selection:
                       new_path_syntax: true
    # See: https://squidfunk.github.io/mkdocs-material/setup/adding-a-git-repository/#revision-date
    - git-revision-date-localized:
        fallback_to_build_date: true
        enable_creation_date: false


#  ╭──────────────────────────────────────────────────────────╮
#  │               Enabling Markdown extensions               │
#  ╰──────────────────────────────────────────────────────────╯
#   https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown/
markdown_extensions:
  # The Table of Contents extension automatically generates a table of contents from a document, 
  # which Material for MkDocs will render as part of the resulting page.
  - toc:
      permalink: true
  # - codehilite:
  #     guess_lang: false
  - admonition
  - pymdownx.details
  - extra
  - pymdownx.superfences
  - pymdownx.tabbed
  - def_list
  - pymdownx.tasklist:
      custom_checkbox: true
  - pymdownx.highlight:
      anchor_linenums: true
  - pymdownx.inlinehilite
  - pymdownx.snippets
  - pymdownx.critic

  # Adding emoji support
  # See: https://squidfunk.github.io/mkdocs-material/reference/icons-emojis/#configuration
  - pymdownx.emoji:
      emoji_index: !!python/name:materialx.emoji.twemoji # (1)!
      emoji_generator: !!python/name:materialx.emoji.to_svg


#  ╭──────────────────────────────────────────────────────────╮
#  │                     Set up navigation                    │
#  ╰──────────────────────────────────────────────────────────╯
# See: https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/

nav:
   - User Guide:
     - user_guide/index.md
     - Command Line Interface: user_guide/cli.md
     - Code Reference:
       - code_reference/index.md
       - Quiz: code_reference/quiz.md
       - Layout: code_reference/layout.md
       - Session: code_reference/session.md
       - Examples: code_reference/examples.md
       - CLI: code_reference/cli.md
   - Learning Guide:
     - learning_guide/index.md
     - Interactive Quiz App: learning_guide/quiz.md
     - Command Line Interface: learning_guide/cli.md
     - Documentation: learning_guide/documentation.md
     - Publishing: learning_guide/publishing.md
     - Testing: learning_guide/testing.md
   - Notebooks:
     - Quizli: notebooks/quizli.ipynb
   - Demos:
     - demos.md

Publish your documentation

Info: Gitlab pages support

While our example below shows a Github Workflow, you could publish your documentation equally well with Gitlab pages.

This might come especially handy if you want to host your own private documentation.

Instructions can be found again in the Publishing your site section

There is a dedicated section in the Material for MkDocs documentation on how to Publish your documentation.

For our purposes, we automate the deployment of the project documentation with a GitHub Actions workflow.

Publishing your docs: .github/workflows/deploy_docs.yml
name: Deploy Docs
on:
  push:
    branches:
      - master
      - main
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
        with:
          python-version: 3.x
      - run: pip install rich typer-cli mkdocs-material mkdocstrings mkdocs-jupyter mkdocs-git-revision-date-localized-plugin ipython_genutils
      - run: mkdocs gh-deploy --force

This way, our documentation is conveniently updated every time we push changes to our git repository.

Using Plugins

There is a great collection of third-party MkDocs plugins.

Below we shortly describe two that we use to further improve quizli's documentation. Feel free to browse the collection for other plugins that suit your needs.

mkdocstrings

With this plugin we can automatically generate documentation from source code.

To enable the plugin we add it to our mkdocs.yml file:

theme:
  name: "material"

plugins:
  - search
  - mkdocstrings

Now we can reference quizli's source code and it will nicely show up in the documentation. For example, since we have documented quizli's source code properly, the following simple reference to it's quiz module:

Example: quiz
::: quizli.quiz
will turn out the following way in the documentation: Quiz - code reference.

You find more advanced usage examples in mkdocstring's documentation.

mkdocs-jupyter

Alternative: mknotebooks

There is an alternative plugin with a similar feature set: mknotebooks

If you want to include jupyter notebooks into your project's documentation check out which one fits your needs better.

This plugin allows us to render jupyter notebooks (or Python scripts) in our documentation.

After installing it, we can enable the plugin again by simply adding a line to our mkdocs.yml file:

plugins:
  - search
  - mkdocstrings
  - mkdocs-jupyter

To give you an example of how it turns out, take a look at the following notebook.

Last update: March 11, 2022