Skip to content

Troubleshooting

What if...

Preview server

... I get an error message in the terminal?

This can happen sometimes. Try those things in the given order:

  • kill the current process in your terminal and start mkdocs serve again.
  • check your mkdocs.yml file for indentation errors.
  • check your mkdocs.yml file for any other errors such as misspelling, invalid variable names, missing parameters etc.
YAML-file

... my website doesn't update?

  • Make sure you saved the updates on your mkdocs.yml.
  • Make sure that you considered the indentation rules in your mkdocs.yml file.
Images and PDFs

... my pdfs and images are not shown?

  • Make sure you used the correct code for inserting an image.
  • Is the path to your image correct?
  • Make sure that the folders where you store your pdfs and images are inside the docs folder. This is important because in your mkdocs.yml file you configured that the directory for your content (=docs_dir) is called docs. So MkDocs expects everything you want to have on your website to be somewhere inside docs.

... my image shows in the local website but not after I deployed it with GitHub?

The deployment server is a bit more sensitive than the preview server.

  • Make sure you used the correct code for inserting an image.
  • Is the path to your image correct?
  • Check the extension of your file. If you changed the extension at some point, the image will not be recognized. E.g., if your image was originally a JPEG (.jpg) and you converted it to a PNG (.png) the image will not be recognized.