5.2 KiB
Troubleshooting MkDocs Material
Read this reference when a build, preview, plugin, Markdown extension, theme override, asset, link, or deployed site fails or behaves unexpectedly.
Diagnostic order
- Capture the exact command, working directory, config path, selected interpreter or image, complete error, and exit code.
- Reproduce in the project's established environment. If several configs
exist, pass the intended one explicitly with
--config-file. - Establish a baseline when possible: did the same command fail before the requested change? Keep new failures separate from existing warnings.
- Classify the failure as YAML/schema, dependency/plugin, content/navigation, Markdown extension, override/asset, or hosting/base-URL related.
- Apply the narrowest correction, rerun the focused command, then rerun the complete project build.
Do not install packages, delete generated output, publish, or rewrite a whole configuration merely to probe a failure unless that action is within the user-approved scope.
Symptom guide
| Symptom | First checks | Typical correction |
|---|---|---|
| YAML parser error | Reported line plus preceding indentation, tabs, duplicate/misnested keys | Repair the smallest YAML structure and validate again. |
Config value 'plugins' error |
Exact plugin name, active environment, dependency declarations, plugin docs | Correct the key or declare/install a compatible package with authorization. |
Page in nav is missing |
docs_dir, spelling/case, suffix, generated-page timing |
Make the path relative to docs_dir or create the intended page. |
| Unknown Markdown extension | Active interpreter, extension name, dependency version | Use the documented extension identifier and compatible installed package. |
| Tabs render as plain text | pymdownx.tabbed, indentation, alternate_style, companion fences for nested code |
Enable/configure the extension and fix page syntax; content.tabs.link alone is insufficient. |
| Override template not found or broken | theme.custom_dir, relative path, upstream template name, Material version |
Fix the override path or update the minimal block override for the installed version. |
| CSS/JavaScript missing | Path under docs_dir, extra_css/extra_javascript, browser network errors, instant navigation lifecycle |
Correct the asset declaration and reinitialize page-specific JavaScript when required. |
| Strict build aborts on warnings | First warning, normal-build output, baseline before the change | Fix regressions; report unrelated existing warnings separately instead of hiding them. |
| Links break only under a hosted subpath | site_url, hosting base path, absolute /... links, CI artifact layout |
Set the real canonical subpath and use generated/internal relative links appropriately. |
| Preview works but deployed site fails | CI command, dependency versions, config selection, environment variables, case-sensitive paths | Reproduce the production build inputs and correct the differing assumption. |
Version and environment mismatches
Dependency declarations, installed packages, the command on PATH, and a CI
image can all describe different versions. Capture version evidence from the
same execution path that fails. With local Python, prefer:
python -m mkdocs --version
python -m pip show mkdocs-material
Use the project's interpreter in place of generic python when one is defined.
For containers, inspect the Dockerfile/image inputs and run version commands in
the project image if it already exists. Do not silently fall back to a global
MkDocs executable.
When current online documentation differs from the installed release, either use the installed release's supported form or propose a separately authorized upgrade. Label behavior that cannot be verified rather than inventing a key.
Build warnings and strict mode
--strict converts warnings into build failures. It is valuable as a project
policy or final clean-build gate, but it does not identify which change caused
an old warning.
- Run the repository's normal build command and retain its warnings.
- Compare with a pre-change run, CI history, or an unchanged revision when available.
- Fix warnings introduced by the requested work.
- Report unrelated warnings by message and affected path; do not suppress them or expand scope silently.
- Run strict mode when the project requires it or after the warning set is understood.
Preview versus deployment
mkdocs serve is a live-reload development server. A successful preview does
not verify the production base URL, generated artifact, CI dependencies,
case-sensitive filesystem, caching, redirects, or host configuration. Build the
site using production-equivalent inputs and inspect the actual publishing
workflow. Running that workflow still requires authorization because it changes
external state.