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