MkDocs v2 compatibility¶
MkDocs v2.0 will remove the plugin system. It cannot run mkdocs-quiz or other MkDocs plugins. It also changes the theme system, so it is not a drop-in upgrade for an existing MkDocs 1.x site.
The mkdocs-quiz dependency is pinned to mkdocs>=1.5,<2. This prevents a routine dependency upgrade from silently installing MkDocs v2.0.
Additionally, Material for MkDocs is now in Maintainance Mode, with end-of-life scheduled for November 5, 2026.
Going forward, users of the mkdocs-quiz plugin have a few options:
Stay on MkDocs 1.x¶
You can continue to use MkDocs 1.x with Material for MkDocs. The mkdocs-quiz version constraint keeps MkDocs below v2.0:
pip install mkdocs-quiz mkdocs-material
Build the site as usual:
mkdocs build
This is a completely fine strategy for now, though be aware that there is some risk due to the upstream packages no longer getting security fixes.
Use ProperDocs and MaterialX¶
ProperDocs is a compatible continuation of MkDocs 1.x. MaterialX is a compatible fork of Material for MkDocs.
You can use either of them if you wish, in place of MkDocs or Material for MkDocs.
To install them both with mkdocs-quiz:
pip install mkdocs-quiz properdocs mkdocs-materialx
Set the theme name in mkdocs.yml or properdocs.yml:
theme:
name: materialx
Then use the ProperDocs command:
properdocs build
Material for MkDocs / MaterialX use the same material Python package. Install only one of these themes in each Python environment.
The mkdocs-quiz CI tests run on both stacks and I will do my best to keep the plugin working with both for as long as I can.