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.

Upgrading MKDocs

To upgrade MKDocs you can use pip

1
2
sudo bash
pip 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.

1
2
3
# 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.

1
2
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

1
2
3
4
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.

1
2
- {% 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