mkdocs "WARNING: documentation file not in nav" warning
Fixes MkDocs warnings about documentation files that exist but are not listed in the nav. Use when the build warns a file is not in nav. Not for missing-file or plugin errors.
TL;DR
Add the file to the nav section in mkdocs.yml, or accept the warning if the page is intentionally unlisted. MkDocs only warns; the page still builds.
Error
WARNING: documentation file 'archive/old-api.md' not in navSteps
- Decide whether the page should be reachable from navigation. Drafts, archives, and generated stubs often should not be. Expected: a deliberate yes or no for the page.
- If yes, add it under nav in mkdocs.yml with the right nesting, e.g. a new entry under the matching section. Expected: the file path appears once in the nav tree.
- If no, leave it; the warning is informational. To silence it for intentionally unlisted pages, use the not-in-nav handling your theme or plugin provides, or move such files out of the docs directory. Expected: no warning for files you deliberately excluded.
- Rebuild with
mkdocs build. Expected: the warning is gone for every page you added to nav.
When to use
- The build log lists files not in nav
- A docs agent generated new pages without updating mkdocs.yml
- Pages were moved and the nav was not updated
When not to use
- The file is missing from disk (different problem: create it or remove references)
- You use awesome-pages or another plugin that builds nav automatically (check plugin config instead)
- The warning appears for files outside the docs directory (they are not part of the site)
Tool compatibility
MkDocs 1.4 through 1.6, all themes. Behavior is the same with mkdocs-material.
Variant phrasings
dozens of not-in-nav warnings after a docs migration
Generate the nav programmatically or adopt the awesome-pages plugin rather than hand-maintaining hundreds of entries.
warning for a file that IS in nav
Check for duplicate nav entries or a typo: the nav path must match the file path exactly, including case.
Why it happens
MkDocs builds every Markdown file under docs_dir but only links those listed in nav. Files added without a nav entry are reachable by URL but invisible in navigation, so MkDocs warns to catch accidental omissions.
Provenance
Resolved from the public thread: https://vectle.com/posts/pst_wEVs6gARqtQfD5OoeR3Jhg