| Name | mkdocs-quizz JSON |
| Version |
0.0.2
JSON |
| download |
| home_page | None |
| Summary | A MkDocs plugin to create quiz |
| upload_time | 2024-09-22 15:23:02 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | None |
| license | MIT |
| keywords |
mkdocs
plugin
quiz
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Mkdocs Quiz
`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.
[](https://github.com/bdallard/mkdocs_quiz/actions/workflows/ci.yml)
## Features
- **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.
## Installation
First, ensure you have MkDocs installed. If you don't, check it out [here](https://github.com/mkdocs/mkdocs).
Install the `mkdocs_quiz` plugin using pip:
```bash
pip install mkdocs_quiz
```
---
## Quick Start Guide
### Create your MkDocs project
If you don't already have a MkDocs project, create one:
```bash
mkdocs new my-project
cd my-project
```
Your project directory should look like this:
```
my-project/
├── docs/
│ ├── javascripts/
│ │ └── extra.js
│ ├── stylesheets/
│ │ └── extra.css
│ └── static/
│ └── audios/
│ └── images/
│ └── videos/
├── mkdocs.yml
└── quizzes.json
```
### Update `mkdocs.yml`
Configure your `mkdocs.yml` to include the plugin and reference necessary CSS and JavaScript files:
```yaml
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.js
```
### Create your json quiz file
Create 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:
```json
{
"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 `indice` are included if `show_indice_on_answer` is set to `true` in your configuration, same for the other options 🤓
### Integrate your quizzes in your markdown files
Include quizzes in your documentation by referencing them in your Markdown files using the `<!-- QUIZ_ID: quiz_name -->` syntax.
Example `docs/index.md`:
```markdown
# Geography Quiz
Test your knowledge about world capitals.
<!-- QUIZ_ID: quiz1 -->
# Space Quiz
Challenge yourself with questions about space.
<!-- QUIZ_ID: quiz2 -->
```
### Run the Documentation Site
Start the MkDocs development server to test your site with quizzes:
```bash
mkdocs serve
```
Open your browser and navigate to `http://localhost:8000` to see your quizzes in action.
---
## Testing
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.
### Tools used
- **unittest**: For writing unit tests.
- **BeautifulSoup**: For parsing and asserting HTML content.
- **mock**: For simulating quiz data.
### Test structure
The test suite is organized into four main files:
1. **`test_html_generation.py`**: Tests for generating quiz HTML
2. **`test_logic.py`**: Tests for quiz logic and functionality
3. **`test_ui_components.py`**: Tests for optional UI elements
4. **`test_mock.py`**: End-to-end testing with mock data integration
### Running test with `tox`
To run the tests, use the `tox` command:
```bash
tox
```
Raw data
{
"_id": null,
"home_page": null,
"name": "mkdocs-quizz",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "mkdocs plugin quiz",
"author": null,
"author_email": "benjamin@proton.me",
"download_url": "https://files.pythonhosted.org/packages/e9/b1/e31ff459ee7af96a34ca4aa80bf3af72a3475e279186ee726daba50c3e75/mkdocs_quizz-0.0.2.tar.gz",
"platform": null,
"description": "# Mkdocs Quiz\n\n`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.\n\n[](https://github.com/bdallard/mkdocs_quiz/actions/workflows/ci.yml)\n\n## Features\n\n- **Multiple Quiz Types**: Support for various question formats.\n- **Media Support**: Include images, videos, and audio in your quizzes.\n- **Multi-language Support**: Define questions and options in multiple languages.\n- **Customizable Options**: Control quiz behavior through configuration settings.\n- **Progress Tracking**: Display scores and progress bars.\n- **Hints and Indices**: Provide hints based on user responses.\n\n## Installation\n\nFirst, ensure you have MkDocs installed. If you don't, check it out [here](https://github.com/mkdocs/mkdocs).\n\nInstall the `mkdocs_quiz` plugin using pip:\n\n```bash\npip install mkdocs_quiz\n```\n\n---\n\n## Quick Start Guide\n\n### Create your MkDocs project\n\nIf you don't already have a MkDocs project, create one:\n\n```bash\nmkdocs new my-project\ncd my-project\n```\n\nYour project directory should look like this:\n\n```\nmy-project/\n\u251c\u2500\u2500 docs/\n\u2502 \u251c\u2500\u2500 javascripts/\n\u2502 \u2502 \u2514\u2500\u2500 extra.js\n\u2502 \u251c\u2500\u2500 stylesheets/\n\u2502 \u2502 \u2514\u2500\u2500 extra.css\n\u2502 \u2514\u2500\u2500 static/\n\u2502 \u2514\u2500\u2500 audios/\n\u2502 \u2514\u2500\u2500 images/\n\u2502 \u2514\u2500\u2500 videos/\n\u251c\u2500\u2500 mkdocs.yml\n\u2514\u2500\u2500 quizzes.json\n```\n\n### Update `mkdocs.yml`\n\nConfigure your `mkdocs.yml` to include the plugin and reference necessary CSS and JavaScript files:\n\n```yaml\nsite_name: My Docs\n\nplugins:\n - search\n - mkdocs_quiz:\n quiz_file: quizzes.json\n language: en\n show_refresh_button: true\n show_indice_on_answer: true\n show_score: true\n show_progress_bar: true\n logging: true\n\nextra_css:\n - stylesheets/extra.css\n - https://cdn.jsdelivr.net/npm/tailwindcss@2.2.19/dist/tailwind.min.css\n\nextra_javascript:\n - javascripts/extra.js\n```\n\n### Create your json quiz file\n\nCreate 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:\n\n```json\n{\n \"quizzes\": {\n \"quiz1\": {\n \"questions\": [\n {\n \"type\": \"multiple-choice\",\n \"question\": {\n \"en\": \"What is the capital of France?\",\n \"fr\": \"Quelle est la capitale de la France?\"\n },\n \"media\": {\n \"type\": \"image\",\n \"src\": \"./static/images/paris.png\",\n \"alt\": {\n \"en\": \"Paris\",\n \"fr\": \"Paris\"\n }\n },\n \"options\": [\n {\n \"text\": {\n \"en\": \"Berlin\",\n \"fr\": \"Berlin\"\n },\n \"correct\": false,\n \"indice\": {\n \"en\": \"Berlin is the capital of Germany.\",\n \"fr\": \"Berlin est la capitale de l'Allemagne.\"\n }\n },\n {\n \"text\": {\n \"en\": \"Madrid\",\n \"fr\": \"Madrid\"\n },\n \"correct\": false,\n \"indice\": {\n \"en\": \"Madrid is the capital of Spain.\",\n \"fr\": \"Madrid est la capitale de l'Espagne.\"\n }\n },\n {\n \"text\": {\n \"en\": \"Paris\",\n \"fr\": \"Paris\"\n },\n \"correct\": true,\n \"indice\": {\n \"en\": \"Correct! Paris is known as the City of Light.\",\n \"fr\": \"Correct! Paris est connue comme la Ville Lumi\u00e8re.\"\n }\n },\n {\n \"text\": {\n \"en\": \"Rome\",\n \"fr\": \"Rome\"\n },\n \"correct\": false,\n \"indice\": {\n \"en\": \"Rome is the capital of Italy.\",\n \"fr\": \"Rome est la capitale de l'Italie.\"\n }\n }\n ]\n },\n {\n \"type\": \"true-false\",\n \"question\": {\n \"en\": \"The Earth is flat.\",\n \"fr\": \"La Terre est plate.\"\n },\n \"media\": {\n \"type\": \"video\",\n \"src\": \"./static/videos/earth.mp4\",\n \"alt\": {\n \"en\": \"Earth\",\n \"fr\": \"Terre\"\n }\n },\n \"options\": [\n {\n \"text\": {\n \"en\": \"True\",\n \"fr\": \"Vrai\"\n },\n \"correct\": false,\n \"indice\": {\n \"en\": \"Incorrect. The Earth is round.\",\n \"fr\": \"Incorrect. La Terre est ronde.\"\n }\n },\n {\n \"text\": {\n \"en\": \"False\",\n \"fr\": \"Faux\"\n },\n \"correct\": true,\n \"indice\": {\n \"en\": \"Correct! The Earth is spherical.\",\n \"fr\": \"Correct! La Terre est sph\u00e9rique.\"\n }\n }\n ]\n },\n {\n \"type\": \"fill-in-the-blank\",\n \"question\": {\n \"en\": \"____ is the largest planet in our solar system.\",\n \"fr\": \"____ est la plus grande plan\u00e8te de notre syst\u00e8me solaire.\"\n },\n \"media\": {\n \"type\": \"audio\",\n \"src\": \"./static/audios/jupiter.mp3\",\n \"alt\": {\n \"en\": \"Largest planet\",\n \"fr\": \"Plus grande plan\u00e8te\"\n }\n },\n \"answer\": {\n \"en\": \"Jupiter\",\n \"fr\": \"Jupiter\"\n },\n \"indice\": {\n \"en\": \"Hint: It's a gas giant.\",\n \"fr\": \"Indice: C'est une g\u00e9ante gazeuse.\"\n }\n },\n {\n \"type\": \"multi-choice\",\n \"question\": {\n \"en\": \"Select the primary colors:\",\n \"fr\": \"S\u00e9lectionnez les couleurs primaires :\"\n },\n \"options\": [\n {\n \"text\": {\n \"en\": \"Red\",\n \"fr\": \"Rouge\"\n },\n \"correct\": true,\n \"indice\": {\n \"en\": \"Red is a primary color.\",\n \"fr\": \"Le rouge est une couleur primaire.\"\n }\n },\n {\n \"text\": {\n \"en\": \"Blue\",\n \"fr\": \"Bleu\"\n },\n \"correct\": true,\n \"indice\": {\n \"en\": \"Blue is a primary color.\",\n \"fr\": \"Le bleu est une couleur primaire.\"\n }\n },\n {\n \"text\": {\n \"en\": \"Green\",\n \"fr\": \"Vert\"\n },\n \"correct\": false,\n \"indice\": {\n \"en\": \"Green is a secondary color.\",\n \"fr\": \"Le vert est une couleur secondaire.\"\n }\n },\n {\n \"text\": {\n \"en\": \"Yellow\",\n \"fr\": \"Jaune\"\n },\n \"correct\": true,\n \"indice\": {\n \"en\": \"Yellow is a primary color.\",\n \"fr\": \"Le jaune est une couleur primaire.\"\n }\n }\n ]\n }\n ]\n }\n // Add more quizzes as needed\n }\n}\n```\n\n> Ensure that fields like `indice` are included if `show_indice_on_answer` is set to `true` in your configuration, same for the other options \ud83e\udd13\n\n### Integrate your quizzes in your markdown files\n\nInclude quizzes in your documentation by referencing them in your Markdown files using the `<!-- QUIZ_ID: quiz_name -->` syntax.\n\nExample `docs/index.md`:\n\n```markdown\n# Geography Quiz\n\nTest your knowledge about world capitals.\n\n<!-- QUIZ_ID: quiz1 -->\n\n# Space Quiz\n\nChallenge yourself with questions about space.\n\n<!-- QUIZ_ID: quiz2 -->\n```\n\n### Run the Documentation Site\n\nStart the MkDocs development server to test your site with quizzes:\n\n```bash\nmkdocs serve\n```\n\nOpen your browser and navigate to `http://localhost:8000` to see your quizzes in action.\n\n--- \n\n## Testing\n\nThis 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.\n\n### Tools used\n\n- **unittest**: For writing unit tests.\n- **BeautifulSoup**: For parsing and asserting HTML content.\n- **mock**: For simulating quiz data.\n\n### Test structure\n\nThe test suite is organized into four main files:\n\n1. **`test_html_generation.py`**: Tests for generating quiz HTML\n2. **`test_logic.py`**: Tests for quiz logic and functionality\n3. **`test_ui_components.py`**: Tests for optional UI elements\n4. **`test_mock.py`**: End-to-end testing with mock data integration\n\n### Running test with `tox`\n\nTo run the tests, use the `tox` command:\n\n```bash\ntox\n```\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A MkDocs plugin to create quiz",
"version": "0.0.2",
"project_urls": {
"Bug Reports": "https://github.com/bdllard/mkdocs_quiz/issues",
"Source": "https://github.com/bdallard/mkdocs_quiz"
},
"split_keywords": [
"mkdocs",
"plugin",
"quiz"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ff098a749603eef1dd0155889c4d31efd386168abf20df2299f6063149ef6311",
"md5": "06450dc5c7327aa8af519760fda33a2a",
"sha256": "585bf7c3a14bd9b50d88535a95ab48393f53c59de23a08bdbc4e3ad28c345c89"
},
"downloads": -1,
"filename": "mkdocs_quizz-0.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "06450dc5c7327aa8af519760fda33a2a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 16518,
"upload_time": "2024-09-22T15:23:00",
"upload_time_iso_8601": "2024-09-22T15:23:00.823094Z",
"url": "https://files.pythonhosted.org/packages/ff/09/8a749603eef1dd0155889c4d31efd386168abf20df2299f6063149ef6311/mkdocs_quizz-0.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e9b1e31ff459ee7af96a34ca4aa80bf3af72a3475e279186ee726daba50c3e75",
"md5": "7d8b94ed509e2c0e54779e49cb937ce2",
"sha256": "ce5ee75585f7a9f37d75a441ba1df787f7479dca8cf37795aca18cbbb12e757d"
},
"downloads": -1,
"filename": "mkdocs_quizz-0.0.2.tar.gz",
"has_sig": false,
"md5_digest": "7d8b94ed509e2c0e54779e49cb937ce2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 13598,
"upload_time": "2024-09-22T15:23:02",
"upload_time_iso_8601": "2024-09-22T15:23:02.190953Z",
"url": "https://files.pythonhosted.org/packages/e9/b1/e31ff459ee7af96a34ca4aa80bf3af72a3475e279186ee726daba50c3e75/mkdocs_quizz-0.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-22 15:23:02",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "bdllard",
"github_project": "mkdocs_quiz",
"github_not_found": true,
"lcname": "mkdocs-quizz"
}
