mkdocs-quiz

MkDocs Quiz Plugin

PyPI version PyPI - Downloads Python versions License

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 incompatability 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!

![Random cat photo](https://cataas.com/cat)
</quiz>
mkdocs-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 -->
mkdocs-quiz

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

CLI Demo

See the CLI Runner documentation for more details.

MkDocs v2 incompatability

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

Changelog

See CHANGELOG.md for version history and changes.

Project links

Data verified by PyPI on Aug 17, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

2 maintainers

PyPI data
Data sourced directly from PyPI's database.
Avatar for ewels from gravatar.com ewels Avatar for skyface753 from gravatar.com skyface753

Credits

PyPI data
Data sourced directly from PyPI's database.

Author: Phil Ewels

GitHub Statistics

Data verified by PyPI on Aug 17, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

Apache Software License (Apache License 2.0)

Requires

Python >=3.9

Provides Extra

dev docs

Tags

mkdocs quiz plugin markdown mkdocs-material multiple-choice exam questions-and-answers

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

mkdocs_quiz-1.7.0.tar.gz (106.6 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

mkdocs_quiz-1.7.0-py3-none-any.whl (94.4 kB view details)

Uploaded Python 3

File details

Details for the file mkdocs_quiz-1.7.0.tar.gz.

File metadata

  • Download URL: mkdocs_quiz-1.7.0.tar.gz
  • Upload date:
  • Size: 106.6 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.13

File hashes

Hashes for mkdocs_quiz-1.7.0.tar.gz
Algorithm Hash digest
SHA256 59a88cf0bc0b65b9042029aefa638a3efcaf86a9219555e7dd6541de6958bba8
MD5 6c91b06b3cafc59bf2c74295249cacd4
BLAKE2b-256 13838378d9799ba5ac7a89d8097c8d9b7e0db0e8bdd2b2f4c8eec1d8181f3265

See more details on using hashes here.

Provenance

The following attestation bundles were made for mkdocs_quiz-1.7.0.tar.gz:

Publisher: publish.yml on ewels/mkdocs-quiz

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file mkdocs_quiz-1.7.0-py3-none-any.whl.

File metadata

  • Download URL: mkdocs_quiz-1.7.0-py3-none-any.whl
  • Upload date:
  • Size: 94.4 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.13

File hashes

Hashes for mkdocs_quiz-1.7.0-py3-none-any.whl
Algorithm Hash digest
SHA256 8ea68326f80e9290c3275deb908cd93c3aafb407a48475089d2a0593425715d8
MD5 a7ce5b1954390babeb48647dd6d61125
BLAKE2b-256 ec5fe9ac121af5c2be2a63a0791fe8f0084f06e245e50eb2cfee165f75de1634

See more details on using hashes here.

Provenance

The following attestation bundles were made for mkdocs_quiz-1.7.0-py3-none-any.whl:

Publisher: publish.yml on ewels/mkdocs-quiz

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

1.7.0 This release

2 files

1.6.5

2 files

1.6.4

2 files

1.6.3

2 files

1.6.2

2 files

1.6.1

2 files

1.6.0

2 files

1.5.4

2 files

1.5.3

2 files

1.5.2

2 files

1.5.1

2 files

1.5.0

2 files

1.4.0

2 files

1.3.0

2 files

1.2.2

2 files

1.2.1

2 files

1.2.0

2 files

1.1.0

2 files

1.0.2

2 files

1.0.1

2 files

1.0.0

2 files

0.0.41

2 files

0.0.40

2 files

0.0.34

2 files

0.0.33

2 files

0.0.32

2 files

0.0.31

2 files

0.0.4

2 files

0.0.3

2 files

0.0.2

2 files

0.0.1

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page