Skip to content

#252: 5 Common Errors in MkDocs and How to Avoid Them

When you are new to MkDocs you may find yourself in front of a few annoying problems. Before you turn your back on this tool, you should try the following troubleshooting tips.

Mapping values are not allowed here - invalid key

Especially when we start expanding our mkdocs.yaml file, we may run into this error:

ConfigurationError: MkDocs encountered an error parsing the configuration file: mapping values are not allowed here

We probably started with a basic setting and then added more configuration values. However, that only works if we append a : at the end of our key:

1
2
  - pymdownx.highlight:
      anchor_linenums: true

Make sure you add the : after your key (here pymdownx.highlight) to fix the error.

Error reading metadata of post - missing a more tag

If we set the option post_excerpt: required in our mkdocs.yaml, we end up with this error should we forget to add the <!-- more --> tag:

1
2
3
4
5
6
7
8
9
mkdocs serve
INFO    -  Building documentation...
INFO    -  Cleaning site directory
ERROR   -  Error reading metadata of post
           'posts\2024\251-create-http-redirects-to-the-new-blog\251-create-http-redirects-to-the-new-blog.md' in
           'docs':
           Expected metadata to be defined but found nothing

Aborted with a BuildError!

To fix this error, we need to add the divider for the post_excerpt:

1
2
3
4
5
Intro...

<!-- more -->
## first heading
...

Now MkDocs can build the site, and everything should work.

Old logos stay on the social cards and on the site – clear cache

If we generate the site and we find an old logo on the images for the social cards, we should delete the .cache folder next to the mkdocs.yaml file:

rm -rf .cache

The next time we generate the site we get a lot of warnings and errors. Wait until MkDocs builds the site and then run the build command again. The errors are now gone, and we have the new logo on our social cards and on our site.

The missing cairo library – follow the instructions

If we configure the image processing according to the documentation, we must follow the whole process. On one machine I got a strange situation. Everything worked the day I installed the Python packages, but the next day I only got this common error:

1
2
3
no library called "cairo-2" was found
no library called "cairo" was found
no library called "libcairo-2" was found

The fix is right there on the documentation site. I did not follow along everything because I could create the images. Prevent yourself from this silly mistake and make sure you install the other packages as well and add them to the path.

Code blocks are not rendered as code blocks – close code block on own line

If we write the markup by hand, we may end up with a code block that looks like this:

The code is not correctly formatted.

This is often the case if we put a closing part of code block not on its own line:

1
2
3
``` py
def fizz_buzz(value):
    return value```

Put the 3 ``` on their own line and the code block shows up as intended:

put the end of the code block on its own line

This should now render your code block correctly:

The correct code block shows now up on your page.

Next

With the most common annoyances out of our way, we can enjoy writing our posts with MkDocs. We continue this series soon with more tricks. But first I must get a bit more experience to point out the helpful parts.

Next week we go back to Pandas and figure out how we can unpivot a pivot table.