## 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
```text
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