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. For top, the desktop menu is anchored 2 px below the real rendered Material header (including a live QR) and follows header/window resizing. 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
Secrets and evaluation access
Do not commit teacher or evaluation passwords in YAML. Point configuration to environment variables instead:
plugins:
- superquiz:
security_mode: obfuscated
teacher_code: env:SUPERQUIZ_TEACHER_CODE
eval:
access:
password: env:SUPERQUIZ_EVAL_PASSWORD
For local development, put the real values in an ignored .env file. For GitLab Pages builds, define the same names under Settings → CI/CD → Variables. The teacher code keeps the existing SHA-256 correction-unlock behavior. Evaluation access emits only a PBKDF2-HMAC-SHA256 verifier into the generated static site; the clear-text evaluation password is not written to GitLab Pages.
A page or diapo.eval frontmatter can override eval.access.password with another env:... variable. Clear-text evaluation passwords in YAML are intentionally rejected.
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.
Encrypted live QR violation snapshot
For page evaluations, eval.qr_report.enabled: true adds a QR code at the far left of the MkDocs SuperQuiz header controls. The QR is regenerated after every recorded violation and is encrypted client-side with a build-generated public RSA key. Scanning it opens a teacher-code-protected viewer on the same static site; no backend is required. eval.show_live_violations is independent and defaults to false.
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.2.tar.gz.
File metadata
- Download URL: mkdocs_superquiz-0.5.2.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 |
37396df22c21bf1b4bbac94efee640951d6325238d61b7dc7359c9ea414209c9
|
|
| MD5 |
29e7b48025e74e7b7ce336fbb1c4f274
|
|
| BLAKE2b-256 |
cb76d5bbffde70748e2dead97ee8417f6e1f630ba8a4bb26c9810a214a41f6e3
|
File details
Details for the file mkdocs_superquiz-0.5.2-py3-none-any.whl.
File metadata
- Download URL: mkdocs_superquiz-0.5.2-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 |
c5fc54f2d5b215a49dd812aecd1207825d202560ed5db24a0236e793d0beba4c
|
|
| MD5 |
c2454a77941f31330b41eece7e4cbf61
|
|
| BLAKE2b-256 |
0a2e1860e3625d709fd38f2a1806022e8ab56f543062a0a452faf228811dd708
|
