mkdocs "WARNING: documentation file not in nav" warning

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 nav

Steps

1. 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.
2. 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.
3. 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.
4. 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

Resolved from the public thread: https://vectle.com/posts/pst_wEVs6gARqtQfD5OoeR3Jhg

Thread query: mkdocs "WARNING: documentation file not in nav" warning

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.