Fullmark Alchemist

English | Tiếng Việt

fullmark: Markdown in, a self-grading offline quiz out.

Try the example quizzes in your browser: nothing to install.

To obtain full marks, something of equal value must be studied. That is the law of Equivalent Exchange.

How this was made

Fullmark was vibe-coded: written almost entirely by AI coding agents (Claude) from my prompts, plans and reviews, with me steering and testing it on my own coursework. The test suite (about 700 tests, including real-browser and accessibility checks) is what keeps it honest. Read the code before trusting it with anything important.

Install

uv tool install fullmark      # or: pipx install fullmark
quiz --help

The command is quiz. Where another program already owns quiz (Debian and Ubuntu's bsdgames ships an old trivia game by that name), use fullmark, which runs the same program.

From source, in a clone of this repository:

uv tool install --editable .

This project was called quizmd before 0.10.0. Version 0.10.0 does not read quizmd results or libraries (the data formats, the config folder and the environment variables were all renamed); rebuild them from your Markdown sources.

After pulling a version that adds a dependency (0.9.0 added tomli-w and rich), reinstall the tool, or the installed quiz fails with ModuleNotFoundError:

uv tool install --editable . --reinstall

For development: uv sync, then uv run pytest (the browser tests need Chromium: uv run playwright install chromium). How a release is made: docs/RELEASING.md.

What it is

Turn a Markdown file into one self-contained HTML quiz that opens by double-click, grades itself offline, and exports the learner's answers as JSON so an AI can review them. The page follows the muted pastel palette: soft paper in light mode, soft slate in dark mode. A quiz can lock its theme (theme: light), as the IELTS example does to resemble the real exam screen.

Docs: agent guide (Tiếng Việt), user guide (web), design spec, and a quiz about this project.

Screenshots

The start screen: what the quiz holds, the suggested time per section, Focus mode, and when you would finish if you start now.

Questions, with the timer, progress and question map beside them:

An ordering question (drag, or the Up and Down buttons) and written answers that an AI grades from a rubric:

Fullmark and Anki

They do different jobs.

Use both: Anki for what you must recall, Fullmark to check you can use it under exam conditions.

The loop

1. An AI reads study material and writes a quiz in fullmark Markdown (quiz guide prints the format).
2. quiz check quiz.md validates it with line-numbered errors; fix until it passes.
3. quiz build quiz.md --open produces quiz.html.
4. The learner answers, presses Submit, then Export answers (results.json).
5. quiz grade results.json --quiz quiz.md writes a Markdown report; an AI grades essays and code from it.

Two layers: core and library

• Core (quiz check, build, serve, grade, ...) works on files: Markdown in, one HTML page or a JSON file out. It needs no setup and no config, and it is all you need to make a quiz and share it.
• Library (quiz library ..., new in 0.9.0, design in docs/plans/LIBRARY_PLAN.md) owns your own quizzes in one folder under git: register a quiz once (the source can be a throwaway file), take it with quiz library take NAME, and every result is filed next to the version you answered. Pages are built on the spot, so they always use the installed fullmark. It calls core and adds nothing to the pages, so a shared page stays the normal offline file. Core never depends on it.

Core commands

Library commands

Eleven commands, all under quiz library. Exit codes: 0 done, 1 problems found (or a refused quiz), 2 usage error or nothing to work on, 3 needs input from the user (register with no library). The design is in docs/plans/LIBRARY_PLAN.md.

Later, when needed: sync, replay, --web (see docs/PLANNED.md). The work order for grade, stats, rename and rm is docs/plans/LIBRARY_HOUSEKEEPING_PLAN.md.

Backups

The library is a plain folder under local git history, which protects against mistakes (a hand-edited snapshot, a broken file) but not against losing the drive. fullmark commits after each init, register, take, grade, rename and rm, and it never pushes. Results hold your answers and the snapshots hold the answer keys, so push only to a private remote. To back up automatically, add a post-commit hook in the library's .git/hooks that runs git push; that is your hook, not fullmark's.

Question types

Single choice, multiple answer, true/false, numeric (tolerances, fractions), short answer (accepted strings and regexes), fill-in-the-blank (also inside code blocks), labeled fields, matching, ordering, essay and code (both exported for AI grading). Questionnaires add ungraded questions and rating scales (mode: survey). LaTeX math (KaTeX, embedded only when used), highlighted code, images and audio are embedded as data URIs. Timers, instant or end-of-quiz feedback, question banks with a random draw, resume after reload, Focus mode, and a versioned JSON export are built in. A choice can ask for a few words when picked (- [ ] Something else {input="What is it?"}); the text is exported and reported but never graded.

A minimal quiz:

---
title: Capitals
---

## What is the capital of France?

- [ ] Lyon
- [x] Paris

> [!explanation]
> Paris has been the capital since 987.

Notes

• The answer key ships inside the HTML, lightly obfuscated (XOR with a key derived from the quiz hash). This stops casual peeking only. It is not an exam-security feature.
• The page makes no network requests; a Content Security Policy blocks them, and the browser tests assert it.
• Project config: .markdownlint-cli2.jsonc (the user's rules, minus MD025 and MD028, which the format needs), biome.json for the runtime JavaScript.
• Regenerate fixtures and example images: uv run python tests/fixtures/make_fixtures.py, uv run python tests/make_grading_cases.py, uv run python src/fullmark/examples/make_assets.py, uv run python docs/build_docs.py (rebuilds docs/GUIDE.html, docs/fullmark-project.html and docs/index.html, the GitHub Pages front page).
• KaTeX 0.16.47 is vendored in src/fullmark/vendor/katex/ (MIT, see its LICENSE).