Metadata-Version: 2.4
Name: mkdocs_quiz
Version: 1.6.0
Summary: A MkDocs plugin to create interactive quizzes in your markdown.
Author-email: Phil Ewels <phil.ewels@seqera.io>, Sebastian Jörz <sjoerz@skyface.de>
License: Apache License 2.0
Project-URL: Homepage, https://ewels.github.io/mkdocs-quiz/
Project-URL: Documentation, https://github.com/ewels/mkdocs-quiz
Project-URL: Repository, https://github.com/ewels/mkdocs-quiz
Project-URL: Issues, https://github.com/ewels/mkdocs-quiz/issues
Keywords: mkdocs,quiz,plugin,markdown,mkdocs-material,multiple-choice,exam,questions-and-answers
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development :: Documentation
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mkdocs>=1.5.0
Requires-Dist: importlib-resources>=5.0; python_version < "3.9"
Requires-Dist: polib>=1.1.0
Requires-Dist: questionary>=2.0.0
Requires-Dist: requests>=2.25.0
Requires-Dist: rich-click>=1.7.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: pytest-playwright>=0.4.0; extra == "dev"
Requires-Dist: ruff>=0.8.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: pre-commit>=3.0.0; extra == "dev"
Requires-Dist: babel>=2.9.0; extra == "dev"
Requires-Dist: types-polib>=1.0.0; extra == "dev"
Requires-Dist: types-Markdown; extra == "dev"
Requires-Dist: tomli>=2.0.0; python_version < "3.11" and extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs-material; extra == "docs"
Dynamic: license-file

# MkDocs Quiz Plugin

[![PyPI version](https://badge.fury.io/py/mkdocs-quiz.svg)](https://badge.fury.io/py/mkdocs-quiz)
![PyPI - Downloads](https://img.shields.io/pypi/dm/mkdocs-quiz)
![Python versions](https://img.shields.io/badge/python-3.8%E2%80%933.14-blue)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

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/](https://ewels.github.io/mkdocs-quiz/)**

## 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](https://ewels.github.io/mkdocs-quiz/) to see the plugin in action.

```markdown
<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>
```

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/ewels/mkdocs-quiz/main/docs/images/quiz_readme_dark.png">
  <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/ewels/mkdocs-quiz/main/docs/images/quiz_readme.png">
  <img src="https://raw.githubusercontent.com/ewels/mkdocs-quiz/main/docs/images/quiz_readme.png" alt="mkdocs-quiz">
</picture>

## Installation

Install the package with pip:

```bash
pip install mkdocs-quiz
```

## Quick Start

### 1. Enable the plugin

Add the plugin to your `mkdocs.yml`:

```yaml
plugins:
  - mkdocs_quiz
```

### 2. Add your first question

Create a quiz with radio buttons (only one correct answer):

```markdown
<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):

```html
<!-- mkdocs-quiz intro -->

..quiz content here..

<!-- mkdocs-quiz results -->
```

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/ewels/mkdocs-quiz/main/docs/images/results_confetti_dark.gif">
  <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/ewels/mkdocs-quiz/main/docs/images/results_confetti.gif">
  <img src="https://raw.githubusercontent.com/ewels/mkdocs-quiz/main/docs/images/results_confetti.gif" alt="mkdocs-quiz">
</picture>

## CLI Quiz Runner

Take quizzes directly in your terminal:

```bash
# 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](https://raw.githubusercontent.com/ewels/mkdocs-quiz/main/docs/assets/cli-demo.gif)

See the [CLI Runner documentation](https://ewels.github.io/mkdocs-quiz/cli-runner/) for more details.

## Contributing

Contributions are welcome! Please see [the contribution guidelines](https://ewels.github.io/mkdocs-quiz/contributing/) for details.

## License

This project is licensed under the Apache License 2.0 - see the [`LICENSE` file](https://github.com/ewels/mkdocs-quiz/blob/main/LICENSE) for details.

## Credits

- Original author: [Sebastian Jörz](https://github.com/skyface753)
- Rewritten by: [Phil Ewels](https://github.com/ewels)

## Changelog

See [CHANGELOG.md](https://ewels.github.io/mkdocs-quiz/changelog/) for version history and changes.
