mkdocs-mcq 0.2.0
MkDocs plugin for multiple choice quizzes
License: MIT
Requires Python: >=3.9

# MkDocs MCQ Plugin


An interactive plugin for MkDocs to create and display single and multiple-choice quizzes directly within your documentation.

**[📖 View Live Demo](https://broktoram.github.io/mkdocs-mcq/)**

## Features

- **Multiple Question Types:** Supports both single choice (radio buttons) and multiple choice (checkboxes) questions.
- **Rich Content:** Use standard Markdown within questions, answers, and feedback, including inline code, links, bold/italic text, and even multi-line code blocks.
- **Math Support:** Render mathematical equations using LaTeX syntax in questions and answers with inline (`$x^2$`) and display (`$$\int_0^1 x dx$$`) math.
- **Immediate Feedback:** Users get instant results after submitting an answer, with clear visual indicators for CORRECT, INCORRECT, and MISSED states.
- **Explanations/Details:** Provide detailed feedback for any answer choice to help users learn.
- **Theme Agnostic:** Uses embedded SVG icons to ensure a consistent and polished look on any MkDocs theme, not just Material for MkDocs.
- **Quiz Summary:** Automatically calculates and displays a final score in a styled admonition block after submission.

## Installation

Install the plugin using pip:

```bash
pip install mkdocs-mcq
```

**Note**: This plugin requires the following packages to be present in your MkDocs environment.

- mkdocs>=1.5
- pymdown-extensions>=10.0
- pyyaml>=6.0

## Configuration

To use the plugin, add mcq to the plugins section of your `mkdocs.yml` file. The plugin will automatically configure its dependencies.

```yaml
plugins:
  - mcq
```

## Usage: Authoring Quizzes

To create a quiz, use a fenced code block with the language identifier `mcq`.

### Basic Structure

Each quiz block consists of two parts: a YAML configuration block and the question content written in Markdown's task list format.

````md
```mcq
---
type: single
question: Your question text goes here.
---

- [ ] An incorrect answer.
- [x] The correct answer.
- [ ] Another incorrect answer.
```
````

### Configuration Options

- `question` (required): The question to be displayed. You can use Markdown here, like inline code.  
- `type` (required): The type of question. Must be either "**single**" or "**multiple**".

### Choices

Choices are defined using Markdown's task list syntax.

Use `- [ ]` for an incorrect answer.  
Use `- [x]` for a correct answer.

### Adding Feedback

To add detailed feedback to any choice, place it in a blockquote (`>`) immediately following the choice.

**Note:** Do not include markers like "CORRECT", "Incorrect Answer", etc. in your feedback text. The plugin automatically appends `(CORRECT)`, `(INCORRECT)`, or `(MISSED)` labels to the feedback based on the user's response.

```md
- [x] 8
  > `**` is the exponentiation operator in Python.

- [ ] 6
  > The `**` operator is for exponents, not multiplication.
```

### Math Equations

You can include mathematical equations in questions, choices, and feedback using LaTeX syntax.

**Inline math**: Use single dollar signs: `$E = mc^2$` renders as $E = mc^2$

**Display math**: Use double dollar signs for block equations:
```
$$
\int_0^1 x^2 dx = \frac{1}{3}
$$
```

**Example:**

````md
```mcq
---
type: single
question: What is the derivative of $f(x) = x^2 + 3x + 5$?
---

- [x] $f'(x) = 2x + 3$
  > Correct! Using the power rule: $\frac{d}{dx}(x^2) = 2x$ and $\frac{d}{dx}(3x) = 3$

- [ ] $f'(x) = x + 3$
  > This is incorrect. You need to apply the power rule to each term.
```
````

## Examples

Here are some complete examples demonstrating the plugin's features.

### Example 1: Single-Choice Question

This example demonstrates a simple single-choice question with feedback for each option.

````md
```mcq
---
type: single
question: What is the output of `print(2 ** 3)`?
---

- [ ] 6
  > `2 * 3` would be 6.

- [x] 8
  > `**` is the exponentiation operator in Python.

- [ ] 9
- [ ] 5
```
````

### Example 2: Multiple-Choice with Code Blocks

This example shows a multiple-choice question where the options themselves are multi-line code blocks.

````md
```mcq
---
type: multiple
question: Which of the following are valid Python code? (Select all that apply)
---

- [ ]
  ```python
  echo("Hello World!")
  ```
  > `echo` is not a valid Python function

- [x] 
  ```python
  print("Hello World!")
  ```
  > `print` is a valid Python function

- [ ] 
  ```python
  printf("Hello World!")
  ```
  > `printf` is not a valid Python function

- [ ] 
  ```python
  println("Hello World!")
  ```
  > `println` is not a valid Python function
```
````

### Example 3: Fenced-code block question

````md
```mcq
---
type: single
question: |
  What is the error in the following Python code?
  ```python
  a = 10
  b = "5"
  print(a + b)
  ```
---

- [ ] A `SyntaxError`, because the code is improperly formatted.
  > The syntax of the code is valid Python.

- [x] A `TypeError`, because you cannot add an integer and a string.
  > The `+` operator is not defined between the types `int` and `str`, which raises a `TypeError`.

- [ ] No error, it will print `15`.
  > Python does not automatically convert the string `"5"` to a number in this context.

- [ ] No error, it will print `105`.
  > While some languages might concatenate these, Python raises a `TypeError` instead.
```
````

## License

This project is licensed under the MIT License.