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.

Correction unlocks now use only two canonical QR scopes: question and all_questions. Set correction_granularity: question (the default) for one correction lock per question, or correction_granularity: all_questions for one page-wide unlock. Legacy unlock scopes such as exercise, page, and eval are intentionally unsupported. The global evaluation-toolbar action is named Unlock All Corrections.

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 Corrections 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 transient notification using --mksq-tooltip-font-size (default 1rem) 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.8.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.8-py3-none-any.whl (6.8 MB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: mkdocs_superquiz-0.5.8.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.8.tar.gz
Algorithm Hash digest
SHA256 9dc255727a22e329b0cf41817d60920f747510b8186ab9eab0188f9b8f7c9ac3
MD5 4282832fb842cf93b946510dee8bf5c2
BLAKE2b-256 86c65d7c86161f5e1c9d4bcbdbe9333dac3df28478763e65a765e18b74df9f2a

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for mkdocs_superquiz-0.5.8-py3-none-any.whl
Algorithm Hash digest
SHA256 6017c1466c0d77de92428cda6ef1a5e90ea90824730a48ebbe2036b919f454f3
MD5 172f17c468fcda8905c55ae14134621c
BLAKE2b-256 73941a95488371a80674e22979af7ec4293a3783f9b471b2712b15c517f21fa5

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

This release

0.5.8 This release

2 files

0.5.7

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