Skip to content

Multiple Choice Quizzes

Multiple choice quizzes use checkbox syntax to define questions with selectable answers. The plugin automatically detects whether to display radio buttons or checkboxes based on the number of correct answers.

Single Choice (Radio Buttons)

When there's one correct answer, radio buttons are displayed:

#

What is the answer to the following sum? 

2 + 2


<quiz>
What is the answer to the following sum?
```
2 + 2
```
- [ ] 3
- [x] 4 _(not `four`)_
- [ ] 5
</quiz>

With single-choice quizzes, the answer is submitted automatically when selected (unless auto_submit is disabled).

Multiple Choice (Checkboxes)

When there are multiple correct answers, checkboxes are displayed:

#

Which of these are even numbers?

<quiz>
Which of these are even numbers?
- [x] 2
- [ ] 3
- [x] 4
- [ ] 5
</quiz>

All correct answers, and only correct answers, must be selected to get the question correct. A submit button is always shown for multiple-choice quizzes.

Content Section

The content section is an optional block of markdown that appears after the answers are submitted:

#

Is Python a programming language?

<quiz>
Is Python a programming language?
- [x] Yes
- [ ] No

Did you know that Python was named after
[Monty Python](https://en.wikipedia.org/wiki/Monty_Python)?
</quiz>

The content section can include any markdown formatting - see Advanced Formatting for examples with code blocks, tables, images, and more.

Answer Syntax Variations

All of these checkbox formats are supported:

Syntax Meaning
- [x] Correct answer (lowercase x)
- [X] Correct answer (uppercase X)
- [ ] Incorrect answer (with space)
- [] Incorrect answer (without space)

You can also use asterisks instead of hyphens:

- [x] Correct answer
- [ ] Incorrect answer

Markdown in Questions

Questions can include markdown formatting like bold, italics, and code:

#

What is the result of 2 ** 3 in Python?

<quiz>
What is the result of `2 ** 3` in **Python**?
- [ ] 6
- [x] 8
- [ ] 9

The `**` operator is exponentiation: 2<sup>3</sup> = 8
</quiz>

Markdown in Answers

Answers can also include markdown formatting:

#

Which is the correct Python syntax?

<quiz>
Which is the correct Python syntax?
- [ ] `print "Hello"`
- [x] `print("Hello")`
- [ ] `echo "Hello"`

In Python 3, `print()` is a function, not a statement.
</quiz>

Per-Answer Feedback

The feedback received on the completion of a form can be customised by including a >

This is optional, any entry that does not include any modified answers will receive the standard 'Correct' or 'Incorrect'.

Radio Button

#

Testing multiple answer texts. What is 2 x 2 ?

<quiz>
Testing multiple answer texts.
What is 2 x 2 ?

- [ ] 3
> Nope, but close!
- [x] 4
> Amazing!
- [ ] 6
> No. Stop it.

Anything else in this section should be prepended.
</quiz>

Multiple Choice

#

Testing multiple answer texts. Which of these fruits are yellow.

<quiz>
Testing multiple answer texts.
Which of these fruits are yellow.

- [ ] Orange
> Oranges are _Orange_.
- [x] Banana
- [x] Pineapple
- [ ] Blueberry
> Blueberries are _blue_.
> ...
> You _fool_.
</quiz>

Formatting

The formatting requirements for the per-answer feedback is quite strict. The > markdown must come immediately after an answer (no blank newlines inbetween).

Getting this wrong has two possible scenarios:

  • If on the final answer, it'll be parsed as a Rich Content Section with a markdown blockquote, and shown for all answers
  • If on any other answer, it'll trigger a mkdocs build failure

For example:

<quiz>
The formatting on this quiz question is wrong:
it has blank newlines around the `>`.
It will trigger a build error.

- [ ] Orange

> Oranges are _Orange_.

- [x] Banana
- [x] Pineapple
- [ ] Blueberry
</quiz>

$ mkdocs serve
...
ValueError: Error in quiz #7 in multiple-choice.md (line 311): Orphaned feedback line found after answer 'Orange'. Feedback blockquotes (> ...) must immediately follow their answer with no blank lines in between. Found: > Oranges are _Orange_.
  Quiz preview: Testing multiple answer texts.     Which of these fruits are...

Important Notes

  1. At least one correct answer required: Every quiz must have at least one - [x] answer
  2. Empty lines are ignored: Blank lines between answers are fine
  3. Question comes first: Everything before the first checkbox is the question
  4. Content comes last: Everything after the last answer is the content section

Next Steps