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 12, 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 12, 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.6.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.6-py3-none-any.whl (6.8 MB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: mkdocs_superquiz-0.5.6.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.6.tar.gz
Algorithm Hash digest
SHA256 0f8269eddcc82b3a7a234582d0f42412b76f04f06caa5cffdafec68191798e3b
MD5 eaa79289bcac074b453fb1365305de62
BLAKE2b-256 ae6d000feef81dd013f11512e55f8aad2c9fa8a9b29170363ba9ce51a22ed624

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for mkdocs_superquiz-0.5.6-py3-none-any.whl
Algorithm Hash digest
SHA256 b42b72beeef84bef0427612f047435d1f527306faa30cd9de1a4015c51db6622
MD5 b565ce00574ff747ea3b7ce55dd0dcf7
BLAKE2b-256 88e676baab25bf4b48212bb1ec94bd7869de9ced840215c824963cf46f2dcd9f

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

0.5.7

2 files

This release

0.5.6 This release

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