Metadata-Version: 2.4
Name: mkdocs-superquiz
Version: 0.3.6
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: pytest<9,>=7; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: twine>=6; extra == "dev"
Dynamic: license-file

# mkdocs-superquiz

`mkdocs-superquiz` is a MkDocs plugin for complete heterogeneous page quizzes with multilingual authoring, configurable scoring, MathJax, saved answers, correction locking, relation drawing, drag-and-drop ordering, matrices and flashcards.

## Page V1 public syntax

This version is intentionally breaking. One Markdown page is one complete quiz and every atomic question uses:

```markdown
!!! question "Optional title"
    ---
    type: mcquiz
    points: 2
    ---
    Select every correct answer.

    answers:
      - [A]
      - B
      - [C]
```

Canonical types:

```text
mcquiz, scquiz, blanks, scdropdown, mcdropdown,
order, columns, sentence,
match, match.line, match.bezier,
image, path, graph,
matrix, flashcard
```

Historical public quiz admonitions are not parsed. Only the exact built-in aliases documented in Page V1 are accepted as `type:` values; users may add additional aliases explicitly by language.

## Installation

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

Enable the plugin in `mkdocs.yml`:

```yaml
plugins:
  - search
  - superquiz
```

The full syntax, configuration hierarchy, 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
```

`package.json` is the version source of truth. Normal builds synchronize the Python package version automatically.

## Verification

`yarn bfc` runs:

- frontend and Python builds;
- wheel and source-distribution checks;
- MkDocs documentation build;
- Python tests;
- frontend tests;
- browser smoke tests when Chromium is available;
- JavaScript syntax checks;
- protected-vendor checks;
- canonical architecture checks for all 16 atomic types.

The required `.gitlab-ci.yml` workflow is part of the repository and must remain present in release archives.

## Protected vendor assets

The vendored jsPlumb and QR-code files are not rewritten by Vite. Their SHA-256 hashes are checked during builds and tests.

## License

GNU GPL-3.0-or-later.
