MkDocs "Unrecognised theme name: 'material'" in CI

By Daniel Zoghalchali·Latchkey

mkdocs.yml sets theme: name: material, but the mkdocs-material package is not installed in the runner. MkDocs only knows about themes registered by installed packages, so it rejects the name.

What this error means

mkdocs build fails with "Config value 'theme': Unrecognised theme name: 'material'. The available installed themes are: mkdocs, readthedocs".

Config value 'theme': Unrecognised theme name: 'material'. The available installed themes
are: mkdocs, readthedocs

Common causes

mkdocs-material is not installed in CI

Material is a separate package; if the runner only installed mkdocs, the material theme is not registered and the name is unrecognised.

Docs dependencies were not installed before build

The build step ran before installing the requirements file that pins mkdocs-material.

How to fix it

Install mkdocs-material

1. Add mkdocs-material to your docs requirements.
2. Install requirements before mkdocs build.
3. Rebuild; the available themes now include material.

pip install mkdocs-material
mkdocs build --strict

Pin docs dependencies

Keep Material and any plugins in one requirements file the CI job installs.

# docs/requirements.txt
mkdocs
mkdocs-material

How to prevent it

• Install mkdocs-material in CI, not just mkdocs.
• Pin the theme and plugins in a requirements file.
• Install requirements before the build step.

Frequently asked questions

Related guides

References

• Node.js documentation
• npm CLI documentation
• GitHub Actions documentation