Skip to content

#259: 2 More Common Errors in MkDocs and How to Fix Them

Now that we have fixed the RSS feed, we can move on to two other common errors you may encounter. They are easy to fix, but first you need to know what the problem is.

Messed up tags

If you only need one tag for your post, you may think it should work when we skip the list and just write this code:

1
tags: mkdocs

This will result in a strange rendering that shows each character as its own tag:

Instead of the tag mkdocs we get the tags m, k, d, o, c, s.

To fix that, make sure to always write the list and put each tag on its own line:

1
2
tags: 
  - mkdocs

Missing table of contents in the post

If you open your post and it does not have the table of contents, you may have figured out a convention of MkDocs. If we do not set the title as part of the meta data at the top of the file, we can use a level 1 heading (#) to set the document title. That works great until the moment you have a second level 1 heading. Then everything falls apart and we end up with a page like this:

The page has no title and there is no table of contents.

The table of contents is missing and if we scroll down, the page title will not stick to the top:

The simple fix for this problem is to check that you only have one line marked as a level 1 heading and the rest uses level 2 (##) headings:

# A
abc

## B
123

## C

We now get the title, the table of contents and everything works as expected.

Next

That concludes the common problems I run into while moving from WordPress to MkDocs. I hope these little tricks prevent you from spending hours to figure out a solution. Next week we go for a more positive spin and explore helpful tools for MkDocs.