mkdocs-superquiz
mkdocs-superquiz creates interactive multilingual questions and complete page quizzes in MkDocs. It supports configurable scoring, MathJax, answer persistence, correction locking, relation drawing, drag-and-drop ordering, matrices, flashcards, per-question scores, page totals, navigation and packaged question icons.
Two display contexts
Embedded questions in a normal page
No page front matter is required. Each question is validated independently and can be mixed with ordinary Markdown:
!!! mcquiz "European capitals"
---
points: 2
randomize: answers
---
Select every capital.
answers:
- [Paris]
- [Madrid]
- Lyon
The equivalent generic form is !!! question with type: mcquiz in its mini front matter.
One complete page quiz
Opt in per Markdown page:
---
superquiz:
display: page
---
Every atomic question then uses:
!!! question "Optional title"
---
type: scquiz
points: 1
---
Choose one answer.
answers:
- [A]
- B
Page display adds shared Validate and Reset All actions, a total score, optional timer, question-order randomization, and configurable right/top/bottom navigation. Embedded display keeps independent Validate, reset and score controls and deliberately has no page-wide actions.
Canonical types:
mcquiz, scquiz, blanks, scdropdown, mcdropdown,
order, columns, sentence,
match, match.line, match.bezier,
image, path, graph,
matrix, flashcard
Built-in icons
The package contains a transparent 512 × 512 normal/timer icon pair for every canonical type plus a generic pair. Icons may be disabled, made generic, resized, positioned, or replaced by a site path or URL. match.line reuses the match icon pair.
Timer and component appearance
When a Page timer is enabled without further values, it now defaults to a one-hour countdown that starts on first interaction, can be dragged from the top-right corner, remembers its position, and submits the page at zero.
Author CSS can be layered through timer.style,
appearance.admonition.style, appearance.validate.style, and icons.style.
Icon display dimensions are controlled independently with icons.size,
icons.width, and icons.height. The Material admonition pseudo-icon is
suppressed so only the SuperQuiz type icon is shown.
Installation
pip install mkdocs-superquiz
plugins:
- search
- superquiz
The complete syntax, display-aware configuration priority, scoring rules and executable examples are published on the GitLab Pages documentation site.
Development
The project uses Yarn 4, Vite, setuptools, MkDocs and GitLab CI.
corepack enable
yarn install
python -m pip install -e ".[dev]"
Main commands:
yarn dev
yarn build
yarn build:full
yarn build:full:check
yarn bfc
yarn zip
package.json is the version source of truth. yarn zip creates a clean project archive suitable for review or transfer without modifying the working tree.
Verification
yarn bfc verifies the frontend and Python packages, documentation, Python tests, frontend tests, browser smoke tests when Chromium is available, JavaScript syntax, protected vendor assets, canonical architecture, and the complete icon manifest in both wheel and source distribution.
License
GNU GPL-3.0-or-later.
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.4.5.tar.gz.
File metadata
- Download URL: mkdocs_superquiz-0.4.5.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 |
a98e0e568dd7eceda60c04fb893eeb0853e20e41802ba19ae37d1be92e44d51e
|
|
| MD5 |
47eddaa39532005b30f264496f5ad9f0
|
|
| BLAKE2b-256 |
7ec959404728c9d696fdb7c7fd1e83ff6669037ed27754f9dda6cbd25227c3df
|
File details
Details for the file mkdocs_superquiz-0.4.5-py3-none-any.whl.
File metadata
- Download URL: mkdocs_superquiz-0.4.5-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 |
b7ea0b1302b38304e49f5af72135e804732001e92cb8e3708ff5a60b47857592
|
|
| MD5 |
3d83ec4cb48c6f9d9f9b5e3d07033cc5
|
|
| BLAKE2b-256 |
7cf6b2a4401fc60e81b863c5e096e6691a0ba898c43607d7de44d32ecd8645de
|
