Skip to content

MkDocs Issues

This page collects common MkDocs and documentation-site issues.

Page Exists but Is Not in Navigation

MkDocs may report pages that exist under docs/ but are not listed in mkdocs.yml.

For this repo, that usually means one of the following:

  • A new page was added but not inserted into nav.
  • A renamed page still has an old path in mkdocs.yml.
  • A generated or legacy file should be intentionally excluded or moved.

Use:

mkdocs build --strict

YAML Title Requires Quotes

If a navigation title contains :, YAML may require quotes:

- "Title: With Colon": path/to/page.md

Preferred style for this repo is to avoid : in navigation titles when possible.

Material for MkDocs Warning About MkDocs 2.0

Material may print an upstream MkDocs 2.0 warning. This is currently an informational warning from the theme project and does not indicate that this repo is broken.

Local Preview

Use:

pip install -r requirements.txt
mkdocs serve

Then open:

http://127.0.0.1:8000/