mkdocs-superquiz
mkdocs-superquiz creates interactive multilingual questions for MkDocs and global evaluation sessions with one final validation and score.
Two behaviors
Embedded questions — default
No page mode is required. Each question is independent and gets its own Validate/Reset behavior:
!!! mcquiz "European capitals"
---
points: 2
---
Select every capital.
answers:
- [Paris]
- [Madrid]
- Lyon
Global evaluation
Activate one complete evaluation in page front matter:
---
superquiz:
mode: eval
---
All atomic questions belong to the same evaluation, individual Validate buttons disappear, and the page gets shared Validate, Reset, score, optional timer, randomization, and navigation.
Evaluation navigation is draggable by default. Every page-evaluation position is a focus layout. right replaces Material's right-hand table of contents and hides the left sidebar; left replaces Material's primary navigation and hides the right sidebar; top and bottom hide both desktop sidebars so the quiz content reclaims their width. As soon as Material switches its primary navigation to the hamburger drawer, all four positions converge to a dedicated nested quiz-navigation level. The numbered quiz menu therefore takes precedence at tablet and mobile widths alike, while Material's standard nested-navigation back arrow returns one level to the normal site hierarchy. Set navigation.draggable: false to keep the desktop menu fixed at its configured anchor.
Canonical mode and aliases:
| Canonical | Accepted aliases |
|---|---|
eval |
evaluation, exam, examen, assessment, page.eval, page.evaluation, page.exam, page.examen, page.assessment |
Reveal.js integration
With mkdocs-revealjs >= 0.10, ordinary mode: diapo decks keep SuperQuiz questions embedded automatically. A mode: diapo.eval deck creates an independent evaluation session with global validation, timer, score and numbered navigation.
No SuperQuiz mode is required for ordinary Reveal integration. The equivalent explicit two-dimensional form for a Reveal evaluation is:
revealjs:
mode: diapo
superquiz:
mode: eval
An explicit diapo.eval deck is the compact form and owns the most local evaluation scope.
Configuration priority
Question behavior resolves from least to most local:
built-ins
< mkdocs.yml common
< mkdocs.yml type
< mkdocs.yml eval/embedded
< mkdocs.yml eval/embedded type
< page common/type/eval layers
< Reveal deck common/type/eval layers
< question mini-frontmatter
The most local explicit value wins. Evaluation sessions are scoped independently by page/deck ID.
Installation
pip install mkdocs-superquiz
plugins:
- search
- superquiz
Question types
mcquiz, scquiz, blanks, scdropdown, mcdropdown,
order, columns, sentence,
match, match.line, match.bezier,
image, path, graph,
matrix, flashcard
Development
yarn dev
yarn dev:lan
yarn build
yarn build:full
yarn bfc
yarn zip
yarn dev:lan exposes the MkDocs development server on 0.0.0.0:8000 for testing from another device on the same LAN.
package.json is the version source of truth.
License
GNU GPL-3.0-or-later.
2 maintainers
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file mkdocs_superquiz-0.5.0.tar.gz.
File metadata
- Download URL: mkdocs_superquiz-0.5.0.tar.gz
- Upload date:
- Size: 6.8 MB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.14.6
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
991198da2d1a63161d3442000c2a21e02a57f333bbb415d35b319dc50a0dcf10
|
|
| MD5 |
1b22fae0fae9c5316821e98e1c70921d
|
|
| BLAKE2b-256 |
d00d69555c12e90a60e98ee5aa6197f7caf6b4794523fce928e30cc318f21867
|
File details
Details for the file mkdocs_superquiz-0.5.0-py3-none-any.whl.
File metadata
- Download URL: mkdocs_superquiz-0.5.0-py3-none-any.whl
- Upload date:
- Size: 6.8 MB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.14.6
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
8bbab865bf0cd07b2834eade96633e33d2230ad7b974d8bb56c23f263aff747a
|
|
| MD5 |
3c5b4b838ec64e544a8cb17368c4c182
|
|
| BLAKE2b-256 |
4d8fee6706b45dc32e52e46f494f4b5c0040a3b31945d6f5b424b44c95e13a01
|
