mkdocs_quiz is a MkDocs plugin that allows you to integrate interactive quizzes into your documentation site using custom JSON files. This plugin supports multiple quiz types, including multiple-choice, true-false, fill-in-the-blank questions. It provides options to customize quiz behavior and appearance, enhancing user engagement with your documentation.
- Multiple Quiz Types: Support for various question formats.
- Media Support: Include images, videos, and audio in your quizzes.
- Multi-language Support: Define questions and options in multiple languages.
- Customizable Options: Control quiz behavior through configuration settings.
- Progress Tracking: Display scores and progress bars.
- Hints and Indices: Provide hints based on user responses.
First, ensure you have MkDocs installed. If you don't, check it out here.
Install the mkdocs_quiz plugin using pip:
pip install mkdocs_quizIf you don't already have a MkDocs project, create one:
mkdocs new my-project
cd my-projectYour project directory should look like this:
my-project/
├── docs/
│ ├── javascripts/
│ │ └── extra.js
│ ├── stylesheets/
│ │ └── extra.css
│ └── static/
│ └── audios/
│ └── images/
│ └── videos/
├── mkdocs.yml
└── quizzes.json
Configure your mkdocs.yml to include the plugin and reference necessary CSS and JavaScript files:
site_name: My Docs
plugins:
- search
- mkdocs_quiz:
quiz_file: quizzes.json
language: en
show_refresh_button: true
show_indice_on_answer: true
show_score: true
show_progress_bar: true
logging: true
extra_css:
- stylesheets/extra.css
- https://cdn.jsdelivr.net/npm/tailwindcss@2.2.19/dist/tailwind.min.css
extra_javascript:
- javascripts/extra.jsCreate a quizzes.json file in the root of your project directory. This file will contain your quiz data and configuration options. Here's an example structure:
{
"quizzes": {
"quiz1": {
"questions": [
{
"type": "multiple-choice",
"question": {
"en": "What is the capital of France?",
"fr": "Quelle est la capitale de la France?"
},
"media": {
"type": "image",
"src": "./static/images/paris.png",
"alt": {
"en": "Paris",
"fr": "Paris"
}
},
"options": [
{
"text": {
"en": "Berlin",
"fr": "Berlin"
},
"correct": false,
"indice": {
"en": "Berlin is the capital of Germany.",
"fr": "Berlin est la capitale de l'Allemagne."
}
},
{
"text": {
"en": "Madrid",
"fr": "Madrid"
},
"correct": false,
"indice": {
"en": "Madrid is the capital of Spain.",
"fr": "Madrid est la capitale de l'Espagne."
}
},
{
"text": {
"en": "Paris",
"fr": "Paris"
},
"correct": true,
"indice": {
"en": "Correct! Paris is known as the City of Light.",
"fr": "Correct! Paris est connue comme la Ville Lumière."
}
},
{
"text": {
"en": "Rome",
"fr": "Rome"
},
"correct": false,
"indice": {
"en": "Rome is the capital of Italy.",
"fr": "Rome est la capitale de l'Italie."
}
}
]
},
{
"type": "true-false",
"question": {
"en": "The Earth is flat.",
"fr": "La Terre est plate."
},
"media": {
"type": "video",
"src": "./static/videos/earth.mp4",
"alt": {
"en": "Earth",
"fr": "Terre"
}
},
"options": [
{
"text": {
"en": "True",
"fr": "Vrai"
},
"correct": false,
"indice": {
"en": "Incorrect. The Earth is round.",
"fr": "Incorrect. La Terre est ronde."
}
},
{
"text": {
"en": "False",
"fr": "Faux"
},
"correct": true,
"indice": {
"en": "Correct! The Earth is spherical.",
"fr": "Correct! La Terre est sphérique."
}
}
]
},
{
"type": "fill-in-the-blank",
"question": {
"en": "____ is the largest planet in our solar system.",
"fr": "____ est la plus grande planète de notre système solaire."
},
"media": {
"type": "audio",
"src": "./static/audios/jupiter.mp3",
"alt": {
"en": "Largest planet",
"fr": "Plus grande planète"
}
},
"answer": {
"en": "Jupiter",
"fr": "Jupiter"
},
"indice": {
"en": "Hint: It's a gas giant.",
"fr": "Indice: C'est une géante gazeuse."
}
},
{
"type": "multi-choice",
"question": {
"en": "Select the primary colors:",
"fr": "Sélectionnez les couleurs primaires :"
},
"options": [
{
"text": {
"en": "Red",
"fr": "Rouge"
},
"correct": true,
"indice": {
"en": "Red is a primary color.",
"fr": "Le rouge est une couleur primaire."
}
},
{
"text": {
"en": "Blue",
"fr": "Bleu"
},
"correct": true,
"indice": {
"en": "Blue is a primary color.",
"fr": "Le bleu est une couleur primaire."
}
},
{
"text": {
"en": "Green",
"fr": "Vert"
},
"correct": false,
"indice": {
"en": "Green is a secondary color.",
"fr": "Le vert est une couleur secondaire."
}
},
{
"text": {
"en": "Yellow",
"fr": "Jaune"
},
"correct": true,
"indice": {
"en": "Yellow is a primary color.",
"fr": "Le jaune est une couleur primaire."
}
}
]
}
]
}
// Add more quizzes as needed
}
}Ensure that fields like
indiceare included ifshow_indice_on_answeris set totruein your configuration, same for the other options 🤓
Include quizzes in your documentation by referencing them in your Markdown files using the <!-- QUIZ_ID: quiz_name --> syntax.
Example docs/index.md:
# Geography Quiz
Test your knowledge about world capitals.
<!-- QUIZ_ID: quiz1 -->
# Space Quiz
Challenge yourself with questions about space.
<!-- QUIZ_ID: quiz2 -->Start the MkDocs development server to test your site with quizzes:
mkdocs serveOpen your browser and navigate to http://localhost:8000 to see your quizzes in action.
This test suite ensures the correctness and robustness of the mkdoc-qcm plugin, covering multiple aspects such as HTML generation, quiz logic, UI components, and configuration options.
- unittest: For writing unit tests.
- BeautifulSoup: For parsing and asserting HTML content.
- mock: For simulating quiz data.
The test suite is organized into four main files:
test_html_generation.py: Tests for generating quiz HTMLtest_logic.py: Tests for quiz logic and functionalitytest_ui_components.py: Tests for optional UI elementstest_mock.py: End-to-end testing with mock data integration
To run the tests, use the tox command:
toxThis project is licensed under the MIT License. See the LICENSE file for details.