Examples

This page demonstrates all the different types of quizzes and options available in mkdocs-quiz. Each example shows a working quiz in the "Example" tab and the markdown source code in the "Syntax" tab.

ExampleSyntax

Quiz Progress

Quiz results are saved to your browser's local storage and will persist between sessions.

Reset quiz

!!! info "Quiz Progress"
    <!-- mkdocs-quiz intro -->

Basic Examples

Single Choice Quiz

A quiz with one correct answer displays as radio buttons:

ExampleSyntax

#

What is the answer to the following sum?

2 + 2

3

4 (not four)

5

Full markdown is supported, even things like code blocks:

def checksum(a):
    assert 2 + 2 == 4

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

Full markdown is supported, even things like code blocks:
```python
def checksum(a):
    assert 2 + 2 == 4
```
</quiz>

Multiple Choice Quiz

A quiz with multiple correct answers displays as checkboxes:

ExampleSyntax

#

Which of these are even numbers?

2

3

4

5

Submit

Great! 2 and 4 are both even numbers.

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

Great! 2 and 4 are both even numbers.
</quiz>

Key difference: When there are multiple - [x] correct answers, checkboxes are displayed instead of radio buttons, and users must select all correct answers.

Quiz Without Content

The content section is optional:

ExampleSyntax

#

Is Python a programming language?

Yes

No

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

Answer Syntax Variations

All of these checkbox formats are supported:

• - [x] - Correct answer (with lowercase x)
• - [X] - Correct answer (uppercase X also works)
• - [ ] - Incorrect answer (with space)
• - [] - Incorrect answer (without space)

Markdown in Questions and Answers

Markdown in Questions

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

ExampleSyntax

#

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

6

8

9

The ** operator is exponentiation: 2³ = 8

<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:

ExampleSyntax

#

Which is the correct Python syntax?

print "Hello"

print("Hello")

echo "Hello"

In Python 3, print() is a function, not a statement.

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

Rich Content Section

The content section supports full markdown formatting including headers, bold/italic text, lists, links, code blocks, images, and tables.

Example with Rich Content

ExampleSyntax

#

What is MkDocs?

A static site generator

A database

A web server

A framework

About MkDocs

MkDocs is a fast, simple and downright gorgeous static site generator.

Key features:

• Written in Python
• Uses Markdown for content
• Includes live preview server
• Themeable with many themes available

Learn more at mkdocs.org

<quiz>
What is MkDocs?
- [x] A static site generator
- [ ] A database
- [ ] A web server
- [ ] A framework

## About MkDocs

MkDocs is a **fast**, **simple** and **downright gorgeous** static site generator.

Key features:

- Written in Python
- Uses Markdown for content
- Includes live preview server
- Themeable with many themes available

[Learn more at mkdocs.org](https://www.mkdocs.org)
</quiz>

Example with Code Blocks

You can include code examples in the content section:

ExampleSyntax

#

Which loop syntax is correct in Python?

for item in items:

for (item in items)

foreach item in items

Here's a complete example:

fruits = ["apple", "banana", "cherry"]
for fruit in fruits:
    print(fruit)

This will print each fruit on a new line.

<!-- MKDOCS_QUIZ_PLACEHOLDER_7 -->

Example with Images

ExampleSyntax

#

Which programming language has this logo? 🐍

Python

JavaScript

Ruby

Python's logo features two intertwined snakes!

<quiz>
Which programming language has this logo? 🐍
- [x] Python
- [ ] JavaScript
- [ ] Ruby

![Random cat photo](https://cataas.com/cat)

Python's logo features two intertwined snakes!
</quiz>

Example with Tables

ExampleSyntax

#

What's special about this formula: E = mc²?

It calculates electricity

It relates mass and energy

It describes gravity

Einstein's famous equation shows:

Symbol	Meaning
E	Energy
m	Mass
c	Speed of light

The equation reveals that mass and energy are interchangeable!

<quiz>
What's special about this formula: E = mc²?
- [ ] It calculates electricity
- [x] It relates mass and energy
- [ ] It describes gravity

Einstein's famous equation shows:

| Symbol | Meaning |
|--------|---------|
| E | Energy |
| m | Mass |
| c | Speed of light |

The equation reveals that mass and energy are interchangeable!
</quiz>

You made it to the end of the quiz! See the Results Screen page to read how to add one of these:

Quiz Progress

0 / 0 questions answered (0%)

0 correct

Quiz Complete!

0%

Reset quiz

Markdown Extensions Support

Quizzes automatically use the same markdown_extensions configured in your mkdocs.yml. This means you can use advanced markdown features like syntax highlighting with line numbers, admonitions, and more.

Code with Line Highlighting

If you have pymdownx.highlight configured, you can use line highlighting in quiz code blocks:

ExampleSyntaxmkdocs.yml

#

Testing markdown_extentions. Python code int | str:

def checksum(a):
    assert 2 + 2 == 4

3

4 (not four)

5

<quiz>
Testing `markdown_extentions`. Python code `#!py int | str`:

```python title="test_file.py" linenums="42" hl_lines="3"
def checksum(a):
    assert 2 + 2 == 4
```

- [ ] 3
- [x] 4 *(not `four`)*
- [ ] 5

</quiz>

markdown_extensions:
  - pymdownx.highlight:
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true
  - pymdownx.superfences

Code blocks in the extra content

Markdown extensions also work in the extra content that is shown after questions are answered:

ExampleSyntaxmkdocs.yml

#

What line prints "hello"?

Line 2

Line 1

Line 3

def greet():
    print("hello")
    return True

<quiz>
What line prints `"hello"`?
- [x] Line 2
- [ ] Line 1
- [ ] Line 3

```python hl_lines="2"
def greet():
    print("hello")
    return True
```
</quiz>

markdown_extensions:
  - pymdownx.highlight:
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true
  - pymdownx.superfences

Admonitions in Quizzes

If you have the admonition extension configured, you can use admonitions in quiz content:

ExampleSyntax

#

What type of admonition is shown below?

A warning

An error

A note

Warning

This is a warning admonition!

<quiz>
What type of admonition is shown below?
- [x] A warning
- [ ] An error
- [ ] A note

!!! warning
    This is a warning admonition!
</quiz>

Other Extensions

All markdown extensions configured in your mkdocs.yml work within quizzes, including:

• pymdownx.superfences - Enhanced code blocks
• pymdownx.highlight - Syntax highlighting with options
• pymdownx.inlinehilite - Inline code highlighting
• admonition - Callout boxes
• attr_list - Add attributes to elements
• tables - Markdown tables
• And any other extensions you have configured!

Important Notes

1. Content must be valid markdown/HTML: The content section is processed as markdown and must be valid
2. Checkbox syntax is recognized: Use - [x], - [X], - [ ], or - []
3. At least one correct answer required: Every quiz must have at least one - [x] answer
4. Empty lines are ignored: Blank lines between answers are okay
5. Question comes first: The first block of lines after <quiz> until the first checkbox is always the question