Skip to content

MK Docs Upgrades

Sometimes when upgrading MKDocs or the Material theme there will be breaking changes, beyond upgrading the packages using pip there may be manual steps to take to get your MKDocs to build again. These steps apply to any MKDocs instances.

Before upgrade

If yum doesn't work and it throws the following error,

There was a problem importing one of the Python modules
required to run yum. The error leading to this problem was:

   No module named yum

Please install a package which provides this module, or
verify that the module is installed correctly.
You will need to reinstall python
rpm --reinstall -v http://mirror.centos.org/centos/7/os/x86_64/Packages/python-2.7.5-86.el7.x86_64.rpm
You will need to install/update mkdocs through python3 and pip3
yum install python3
python3 -m pip install --upgrade pip

Upgrading MKDocs

To upgrade MKDocs you can use pip

sudo bash
pip3 install --upgrade mkdocs mkdocs-material

This will upgrade MKDocs and the Material theme to the latest version, you should do this locally and immediately follow up with a build.

# Rebuild MKDocs
cd <mkdocsDir>
mkdocs build --clean

If there are no errors and the output is as you expect in the browser then no further action is required.

Reverting to an older version of Mkdocs

If you wish to avoid the issues with an upgrade to MkDocs, you can force pip to use a specific version. The following commands will use the earliest version of Mkdocs we have adopted which are known to work correctly.

sudo bash
pip install mkdocs==0.16.1 mkdocs-material==1.2.0

Breaking Changes on upgrade

YAML Format Change and Template Overrides (MKDocs 0.16.1 to 0.17.2)

Not reverse compatible

Between these versions, the YAML formatting changed and there were deprecations.

Theme Selection

The setting for the theme itself has moved from theme to theme.name

theme_dir is now deprecated

Use theme.custom_dir instead

site_favicon is deprecated

Use theme.favicon instead

extra is deprecated

Use the theme node instead, move the extra fields to be children of this

Build error - jinja2.exceptions.UndefinedError: 'config' is undefined

This is due to the theme customisations, to fix this, look for a reference to a HTML file in the stack trace

File "/usr/lib/python2.7/site-packages/material/partials/header.html", line 36, in block "search_box"
    {% include "partials/search.html" %}
File "/var/www/vhosts/mkdocs/themeOverrides/partials/search.html", line 23, in top-level template code
  {% import "partials/language.html" as lang %}

All theme customisation should be inside the themeOverrides directory. To fix the issue, we need to add with context to the end of the import referenced in the second file.

- {% import "partials/language.html" as lang %}
+ {% import "partials/language.html" as lang with context %}

Search is broken

Search has changed slightly, the overriding template can be removed.

The extra parameters need to be moved to the new