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 and follows header/window resizing. The draggable evaluation toolbar is a separate overlay placed on the opposite side by default. 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 evaluations, eval.qr_report.enabled: true enables the encrypted live QR snapshot inside the shared draggable evaluation toolbar. The QR is regenerated after every recorded violation and is encrypted client-side with a build-generated public ECDH P-256 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; when enabled, grouped counts appear at the bottom of the same toolbar. In strict, the QR and Reset All are visible by default while Unlock All is hidden by default through eval.toolbar. The toolbar is draggable by default and starts on the side opposite the numbered navigation. In strict mode the toolbar timer is enabled automatically as a 50-minute countdown (overridable, including enabled: false) and stops when final validation succeeds. Every recorded strict violation also emits a stacked 2em transient notification above the UI (z-index: 50000).

Project links

Data verified by PyPI on Aug 13, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.6.2)

2 maintainers

PyPI data
Data sourced directly from PyPI's database.
Avatar for Rod2ik from gravatar.com Rod2ik Avatar for Rodrigo1337 from gravatar.com Rodrigo1337

Credits

Author: Rod2ik, aka Rodrigo Schwencke

GitLab Statistics

Data verified by PyPI on Aug 13, 2026
The GitLab source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

GNU General Public License v3 or later (GPLv3+) (GPL-3.0-or-later)

Requires

Python >=3.8

Provides Extra

dev

Tags

mkdocs quiz superquiz qcm plugin mc sc blanks dropdown order columns match graph flashcard mathjax i18n education interactive markdown

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

mkdocs_superquiz-0.5.7.tar.gz (6.8 MB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

mkdocs_superquiz-0.5.7-py3-none-any.whl (6.8 MB view details)

Uploaded Python 3

File details

Details for the file mkdocs_superquiz-0.5.7.tar.gz.

File metadata

  • Download URL: mkdocs_superquiz-0.5.7.tar.gz
  • Upload date:
  • Size: 6.8 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.14.7

File hashes

Hashes for mkdocs_superquiz-0.5.7.tar.gz
Algorithm Hash digest
SHA256 c102ff498bd8a4afbaabeb2a1b584f0f9fc67fadfe425e0231922f79b807ecf8
MD5 ed7bca6715897d9c6d3a570b4f77de8a
BLAKE2b-256 53eb4e506e4e12cd982319e047fa4e31262674637440dfb7d9f18756779ddd58

See more details on using hashes here.

File details

Details for the file mkdocs_superquiz-0.5.7-py3-none-any.whl.

File metadata

File hashes

Hashes for mkdocs_superquiz-0.5.7-py3-none-any.whl
Algorithm Hash digest
SHA256 6f1ba90c15f27af2857d9295379fe0fbf54b11c295764ab5eeea386342fe53b4
MD5 bfd0d2b71c427f4c903dd19cc2f8ee96
BLAKE2b-256 70cea53b4018dfa58a29d6ffb58e8c0fbe795f6f0e139e37f8a590ab85332773

See more details on using hashes here.

Release history Release notifications | RSS feed

0.6.2

2 files

0.6.1

2 files

0.6.0

2 files

0.5.9

2 files

0.5.8

2 files

This release

0.5.7 This release

2 files

0.5.6

2 files

0.5.5

2 files

0.5.3

2 files

0.5.2

2 files

0.5.1

2 files

0.5.0

2 files

0.4.5

2 files

0.4.3

2 files

0.4.2

2 files

0.3.6

2 files

0.3.4

2 files

0.3.3

2 files

0.3.2

2 files

0.3.0

2 files

0.2.8

2 files

0.2.7

2 files

0.2.3

2 files

0.2.1

2 files

0.2.0

2 files

0.1.26

2 files

0.1.25

2 files

0.1.24

2 files

0.1.23

2 files

0.1.22

2 files

0.1.21

2 files

0.1.20

2 files

0.1.19

2 files

0.1.18

2 files

0.1.17

2 files

0.1.16

2 files

0.1.15

2 files

0.1.14

2 files

0.1.13

2 files

0.1.12

2 files

0.1.11

2 files

0.1.10

2 files

0.1.9

2 files

0.1.8

2 files

0.1.7

2 files

0.1.6

2 files

0.1.5

2 files

0.1.4

2 files

0.1.3

2 files

0.1.2

2 files

0.1.1

2 files

0.1.0

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page