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:

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. Its first click anywhere inside the visible evaluation wrapper requests deck-scoped browser fullscreen before password entry, for both standard and strict; a Reveal password gate therefore stays in fullscreen while the learner authenticates.

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 use two 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. 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

The ordering family (order, columns, sentence) requires an explicit answers: block. A bare Markdown list is not an answer definition. Localized answers aliases remain supported through the normal i18n vocabulary (for example réponses: in French).

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.

The documentation uses an explicit generated vendor for mkdocs-maths-admonitions. yarn vendor:sync reads vendor.config.mjs: locally it prefers ../mkdocs-maths-admonitions/dist even when that sibling is a newer unpublished version, while CI/GitLab Pages always obtains the exact pinned npm release. Both sources are mirrored to site/overrides/vendor/mkdocs-maths-admonitions/, so the MkDocs templates use one stable path in every environment.

Generated output follows the same convention as the other projects: dist/ contains Python distributions, public/ contains the GitLab Pages site, build/ contains intermediates, and site/overrides/vendor/ contains generated documentation vendors. None of these directories is source code.

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_in_toolbar independently controls the persistent grouped counts at the bottom of the toolbar and defaults to false. eval.show_live_violations_tooltips independently controls transient top-right violation notifications and defaults to true. In standard, only violations whose action is warn produce those notifications; in strict, every recorded non-ignored violation does, using the strict-mode notification policy. 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.

All public product defaults are defined in src/mkdocs_superquiz/config.py. evaluation_policy.py validates and resolves them but does not own a second copy of the defaults.

Correction-state icons

The four correction states are intentionally distinct and all four icons are configurable in mkdocs.yml:

plugins:
  - superquiz:
      correction_locked_icon: "❌"    # correction unavailable / show_correction: no
      correction_unlock_icon: "🔐"    # teacher-code unlock is available
      correction_open_icon: "✅"      # correction always visible
      correction_unlocked_icon: "🔓"  # successfully unlocked with teacher code

correction_open_icon replaces the former meaning of correction_unlocked_icon. The name correction_unlocked_icon now exclusively describes the post-teacher-code state. The evaluation toolbar's Unlock All Corrections action uses correction_unlock_icon before unlocking and correction_unlocked_icon after success.