mkdocs build --strict: Fail on Doc Warnings
mkdocs build compiles a MkDocs project into a static site under site/, and --strict makes any warning abort the build.
MkDocs (often with Material) is a popular Markdown docs stack. In CI the one flag that matters is --strict, which promotes broken links and missing nav entries from warnings to hard failures.
What it does
mkdocs build reads mkdocs.yml, processes the Markdown pages, applies the theme, and writes a static site to site/ (or --site-dir). --strict causes MkDocs to exit non-zero if it emits any warning, such as a link to a page that is not in the nav.
Common usage
mkdocs build --strict
# clean the output directory first and pick a custom target
mkdocs build --strict --clean --site-dir publicOptions
| Flag | What it does |
|---|---|
| --strict / -s | Treat warnings as errors (non-zero exit) |
| --clean | Remove old files from the site dir before building |
| --site-dir <dir> | Where to write the built site |
| --config-file <f> | Use a config file other than mkdocs.yml |
| --verbose / -v | Show DEBUG-level build output |
| --no-directory-urls | Emit foo.html instead of foo/ paths |
In CI
Always pass --strict so a bad link fails the pipeline instead of shipping. Cache the pip environment (mkdocs, Material, plugins) rather than the site output. For Material insiders or social cards, ensure the extra system libraries are installed on the runner.
Common errors in CI
Aborted with 3 warnings in strict mode! is the strict-mode failure; scroll up for lines like WARNING - Doc file 'guide.md' contains a link 'missing.md', but the target is not found. Config value 'theme': Unrecognised theme name: 'material' means mkdocs-material is not installed. The following pages exist in the docs directory, but are not included in the "nav" configuration is a common strict-mode trigger.