Metadata-Version: 2.4
Name: mkdocs-superquiz
Version: 0.4.5
Summary: MkDocs plugin to create interactive, multilingual quizzes with scoring, MathJax support and QR-code correction unlocking
Author-email: "Rod2ik, aka Rodrigo Schwencke" <rod2ik.dev@gmail.com>
License: GPL-3.0-or-later
Project-URL: Homepage, https://rod2ik.gitlab.io/mkdocs-superquiz/
Project-URL: Documentation, https://rod2ik.gitlab.io/mkdocs-superquiz/
Project-URL: Repository, https://gitlab.com/rod2ik/mkdocs-superquiz
Project-URL: Issues, https://gitlab.com/rod2ik/mkdocs-superquiz/-/issues
Keywords: mkdocs,quiz,superquiz,qcm,plugin,mc,sc,blanks,dropdown,order,columns,match,graph,flashcard,mathjax,i18n,education,interactive,markdown
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: MkDocs
Classifier: Environment :: Plugins
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Education
Classifier: Topic :: Documentation
Classifier: Topic :: Text Processing :: Markup
Classifier: Topic :: Text Processing :: Markup :: Markdown
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mkdocs<2.0,>=1.5
Requires-Dist: pymdown-extensions>=10.0
Requires-Dist: PyYAML>=6.0
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: mkdocs-material<10,>=9; extra == "dev"
Requires-Dist: mkdocs-revealjs; extra == "dev"
Requires-Dist: Pillow; extra == "dev"
Requires-Dist: pytest<9,>=7; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: twine>=6; extra == "dev"
Dynamic: license-file

# 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:

```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:

```yaml
---
superquiz:
  display: page
---
```

Every atomic question then uses:

```markdown
!!! 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:

```text
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

```bash
pip install mkdocs-superquiz
```

```yaml
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.

```bash
corepack enable
yarn install
python -m pip install -e ".[dev]"
```

Main commands:

```bash
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.
