Python Friday #58: Customise MkDocs

Last week I started an introduction to MkDocs. In this post we change the theme and look at other ways to customise our MkDocs site.

This post is part of my journey to learn Python. You can find the other parts of this series here.

 

Switch theme

The default theme in MkDocs is mkdocs. This theme is used when you do not specify anything in your configuration and looks like this:

MkDocs comes with a second theme called readthedocs. To use this theme, you need to add a line to your mkdocs.yaml:

Run mkdocs serve again and your site looks different:

If you misconfigure MkDocs on purpose and set a name for a theme that does not exist, mkdocs serve will throw an error and give you a list of all installed themes:

INFO – Building documentation…
ERROR – Config value: ‘theme’. Error: Unrecognised theme name: ‘NotValid’. The available installed themes are: mkdocs, readthedocs

 

Install additional themes

For our T4.FileManager documentation we use the Material theme for MkDocs. You can install it with PIP:

After a successful installation you can use the material theme in mkdocs.yaml:

The next time you run mkdocs serve your site will look like this:

 

Add your own logo

Some themes have a logo in the header that you can change. For the material theme you can change it with an entry like this in mkdocs.yaml:

In my example the logo is directly in the docs folder. Should you get an error, create an images folder inside the docs folder and put your logo there – do not forget to change the path to your logo inside mkdocs.yaml.

You may need to restart mkdocs serve and refresh your browser before it shows you the new logo:

Check the documentation for additional ways to customise the Material theme. There are many more things you can change, including the colour scheme.

 

Create a custom theme

You can create your own theme if none of the existing ones fulfils your needs. I did not try that myself yet, but the documentation for custom themes looks like a good starting point.

 

Next

If you want to use MkDocs to document your software project, you need to display code. The next post addresses this point and helps you to overcome the obstacles I run into as I tried it the first time.