Installation¶
mkdocs-quiz requires Python 3.9 or later and MkDocs 1.5 or later. It supports MkDocs 1.x, but not MkDocs 2.
The plugin supports both Material for MkDocs and MaterialX. Do not install both themes in the same Python environment because they use the same material Python package.
See MkDocs v2 compatibility for supported stacks and migration options.
To install mkdocs-quiz from PyPI, you can use pip:
pip install mkdocs-quiz
If your project has a requirements.txt file, add mkdocs-quiz to it and run:
pip install -r requirements.txt
If you're managing your project with uv, you can add it as follows:
uv add mkdocs-quiz
Or to install globally:
uv tool install mkdocs-quiz
For development or to get the latest unreleased features:
git clone https://github.com/ewels/mkdocs-quiz.git
cd mkdocs-quiz
pip install -e ".[dev]"
Choose a Material theme¶
Install Material for MkDocs:
pip install mkdocs-material
Set the theme name in mkdocs.yml:
theme:
name: material
Install MaterialX:
pip install mkdocs-materialx
Set the MaterialX theme name in mkdocs.yml or properdocs.yml:
theme:
name: materialx
MaterialX supports MkDocs 1.x and ProperDocs. See the MaterialX differences for migration details.
Enabling the Plugin¶
Add the plugin to your mkdocs.yml configuration file:
plugins:
- mkdocs_quiz
That's it! The plugin is now active and will process all quiz blocks in your markdown files.
Configuration¶
See the Configuration page for all available options.