mkdocs WARNING: documentation file not in nav warning

Not specified by the original author.

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.

Not specified by the original author.

Fix MkDocs 'file referenced in nav not found' build errors

TL;DR

A nav entry points at a file MkDocs cannot find under docs_dir: a typo, a case mismatch, or a page that was moved or deleted without updating mkdocs.yml. Fix the entry or restore the file, then rebuild. The build passes because every nav path resolves to a real file.

The error

Aborted with 1 Build Errors!
ERROR - File 'guide/setup.md' not found in nav 'Guide > Setup'

Steps

1. Read the exact path from the error message. Expected: the nav path MkDocs tried, e.g. guide/setup.md.

2. Compare against the source tree: ls docs/guide/ and check spelling and letter case. On Linux, Setup.md and setup.md are different files; a build that passes on macOS fails on Linux CI for exactly this reason. Expected: you find the typo, the case difference, or the missing file.

3. Fix it: correct the nav: entry in mkdocs.yml, restore the deleted file, or move the file under docs_dir if it lives elsewhere. Expected: every nav path matches a real file inside docs/.

4. Rebuild: mkdocs build. Expected: exit code 0 and the page appears in the built site navigation.

Use this when

• mkdocs build aborts naming a file it cannot find in nav
• pages renamed or moved without updating mkdocs.yml
• builds pass on macOS but fail on Linux

Not for this skill when

• plugin 'search' is not installed (install problem, not content)
• theme 'material' not found (theme problem)
• warnings about files 'not included in nav' (those are warnings, and the fix is the reverse: add or exclude them)

Variant phrasings

• mkdocs file referenced in nav not found
• mkdocs build error nav file missing
• mkdocs aborted build errors nav
• mkdocs nav entry file does not exist

Why it happens

The nav section is an explicit map from titles to file paths, and MkDocs validates every path against the files it found under docs_dir. Anything that breaks the mapping - a typo, a rename committed without updating mkdocs.yml, a case difference invisible on macOS, a file saved outside docs/ - turns into this build error. It is a hard error rather than a warning because the navigation would otherwise link to a page that was never built.

Edge cases

• Files present under docs/ but absent from nav only produce a warning ('not included in navigation'); decide per file whether to add it to nav or leave it.
• Deeply nested nav makes typos likely; keep the nav tree shallow or generate it only if the team maintains the generator.
• After fixing, run mkdocs build --strict in CI so future nav rot fails the build instead of shipping silently.

Provenance

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

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

Thread query: mkdocs build error: file referenced in nav not found

TL;DR: A nav entry points at a file MkDocs cannot find under docs_dir: a typo, a case mismatch, or a page that was moved or deleted without updating mkdocs.yml. Fix the entry or restore the file, then rebuild. The build passes because every nav path resolves to a real file.

Not specified by the original author.

Fix MkDocs "plugin 'search' is not installed" build aborts

TL;DR

The search plugin ships inside MkDocs itself, so this error means the MkDocs installation is broken or the mkdocs binary comes from a different Python environment than the installed package. Reinstall MkDocs in the right environment and confirm the binary matches, then rebuild. The plugin resolves because MkDocs is whole again.

The error

Aborted with 1 Configuration Errors!
ERROR - Config value 'plugins': The "search" plugin is not installed

Steps

1. Check the install: mkdocs --version. Expected: a version string like 'mkdocs, version 1.5.3'. If the command is missing, MkDocs is not installed in this shell at all.

2. Reinstall in the active environment: pip install mkdocs, or pip install --force-reinstall mkdocs if the version prints but the error persists. Expected: pip reports a successful install.

3. Confirm the binary and the package agree: which mkdocs and pip show mkdocs should point at the same environment (same bin/ and lib/ prefix). Expected: one environment owns both; a mismatch here is the usual culprit.

4. Also scan mkdocs.yml plugins: for typos - a misspelled plugin name produces the identical "not installed" error for that name. Expected: every listed plugin name is spelled correctly.

5. Rebuild: mkdocs build. Expected: exit code 0 with 'Documentation built' output and no plugin error.

Use this when

• mkdocs build aborts claiming the built-in search plugin is missing
• the error appears right after switching virtualenvs or containers
• CI builds fail while the local build works

Not for this skill when

• a third-party plugin reported as not installed (that one genuinely needs pip install)
• theme 'material' not found (theme problem, separate package)
• 'file referenced in nav not found' (a content problem, not an install problem)

Variant phrasings

• mkdocs plugin search is not installed
• mkdocs aborted configuration errors plugins
• mkdocs search plugin missing
• mkdocs build plugin not installed error

Why it happens

MkDocs loads plugins by entry point, and search is registered by MkDocs itself at install time. When the metadata is corrupted - a partial install, an interrupted upgrade - or when the mkdocs script on PATH belongs to a different interpreter than the one pip installed into, the entry point lookup fails and MkDocs reports its own built-in plugin as missing. The message is misleading; the installation is what is broken, not the plugin list.

Edge cases

• Multiple Pythons on PATH make pip and mkdocs disagree silently; python -m pip install mkdocs plus python -m mkdocs build forces them into the same interpreter.
• An interrupted pip install --upgrade mkdocs leaves exactly this half-installed state; --force-reinstall repairs it.
• If you do not want search at all, remove it from the plugins list rather than fighting the install - but the error then was never about search itself.

Provenance

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

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

Thread query: mkdocs build "Error: plugin 'search' is not installed" aborted

TL;DR: The search plugin ships inside MkDocs itself, so this error means the MkDocs installation is broken or the mkdocs binary comes from a different Python environment than the installed package. Reinstall MkDocs in the right environment and confirm the binary matches, then rebuild. The plugin resolves because MkDocs is whole again.