MkDocs Quiz Plugin
A modern MkDocs plugin to create interactive quizzes directly in your markdown documentation. Perfect for educational content, tutorials, and documentation that requires user engagement.
📚 Documentation and examples: https://ewels.github.io/mkdocs-quiz/
[!IMPORTANT] The upcoming MkDocs v2.0 will remove plugin support, so it cannot run
mkdocs-quiz. mkdocs-quiz pins MkDocs <v2.0. See MkDocs v2 incompatibility for details and compatible alternatives to MkDocs.
[!TIP] Building with Astro instead?
Try starlight-quiz, which uses the same markdown quiz syntax and works with both Starlight and vanilla Astro.
Features
- ✨ Simple markdown syntax - Create quizzes using GitHub-flavored markdown checkboxes
- 🎯 Multiple quiz types - Single choice (radio), multiple choice (checkboxes), and fill-in-the-blank
- ⚡ Instant feedback - Visual indicators show correct/incorrect answers
- 📊 Progress tracking - Automatic progress sidebar and results panel, with confetti 🎉
- 💾 Results saved - Answers are saved to the browser's local storage
- 🌐 Internationalization - Quiz elements support multi-lingual sites
- 📤 LMS Export - Export quizzes to QTI format for Canvas, Blackboard, Moodle
- 🖥️ CLI Quiz Runner - Take quizzes in your terminal, from local files or website URLs
[!TIP] Check out the documentation to see the plugin in action.
<quiz>
What's the best static site generator?
- [x] mkdocs
- [ ] Jekyll
- [ ] Sphinx
If you entered mkdocs, you've come to the right place!
</quiz>
Installation
Install the package with pip:
pip install mkdocs-quiz
Quick Start
1. Enable the plugin
Add the plugin to your mkdocs.yml:
plugins:
- mkdocs_quiz
2. Add your first question
Create a quiz with radio buttons (only one correct answer):
<quiz>
What is 2+2?
- [x] 4
- [ ] 3
- [ ] 5
Correct! Basic math is important.
</quiz>
Use - [x] for correct answers and - [ ] for incorrect answers.
If multiple answers are correct, checkboxes instead of radio buttons will be shown (the user has to select all correct answers).
3. Intro text and results
Insert these placeholder comments for some intro text with a reset button and a final results panel (which shoots confetti when you finish):
<!-- mkdocs-quiz intro -->
..quiz content here..
<!-- mkdocs-quiz results -->
CLI Quiz Runner
Take quizzes directly in your terminal:
# Interactive mode - select from discovered quizzes in the current repository
# (you can also use `mkdocs-quiz` instead of `quiz`)
quiz
# Run from a website URL
quiz run https://ewels.github.io/mkdocs-quiz/multiple-choice/
# Run a specific file
mkdocs-quiz run docs/quiz.md
See the CLI Runner documentation for more details.
MkDocs v2 incompatibility
This package requires mkdocs>=1.5,<2, which prevents dependency upgrades from silently installing MkDocs 2.0. You can continue to use MkDocs 1.x with Material for MkDocs.
mkdocs-quiz supports the compatible ProperDocs fork of MkDocs and MaterialX fork of Material for MkDocs. Find more details about how to use these in the mkdocs-quiz documentation.
Contributing
Contributions are welcome! Please see the contribution guidelines for details.
License
This project is licensed under the Apache License 2.0 - see the LICENSE file for details.
Credits
- Original author: Sebastian Jörz
- Rewritten by: Phil Ewels
Changelog
See CHANGELOG.md for version history and changes.
2 maintainers
Metadata
2 maintainers
Release files for mkdocs-quiz 1.7.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| mkdocs_quiz-1.7.1.tar.gz | 109.2 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| mkdocs_quiz-1.7.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 206.1 kB
Release files / mkdocs_quiz-1.7.1.tar.gz
| Download URL | mkdocs_quiz-1.7.1.tar.gz |
|---|---|
| Size | 109.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
85428c39a37df116c3cfc4483f990ff182e869bd0b64fe823edbaec317626260
|
|
BLAKE2b-256 checksum How to use checksums |
483766b7337ac4340d029046c4b4c8514131f209997641adaef3650c022d70a6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 8, 2026.
Transparency logRelease files / mkdocs_quiz-1.7.1-py3-none-any.whl
| Download URL | mkdocs_quiz-1.7.1-py3-none-any.whl |
|---|---|
| Size | 97.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ac7d5e72c28b9a048f5b619acfffab0f39dccb4a2e1747c5ee9b694d74d6a08e
|
|
BLAKE2b-256 checksum How to use checksums |
0c7d11ca3b3d01cfc414ad8d75a31f29c89834a3e8710d862be82130c734456e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 8, 2026.
Transparency log
