QuizMD
The assessment format of the LearnSpec suite.
QuizMD uses Markdown with progressive YAML configuration to create quizzes, exams, and assessments, from simple practice questions to full scored exams with timed sections, all in portable plain-text files.
LearnMD covers instruction; QuizMD covers assessment. The two compose freely: a .quiz.md can be embedded inline in a lesson via !import.
Key principles
| Principle | Description |
|---|---|
| YAML everywhere | One configuration syntax across three progressive levels |
| Markdown-first | Valid Markdown files readable in any editor |
| File-native | All content lives in files, no database required |
| AI-native | Generatable and consumable by LLMs without special tooling |
| Rich question types | MCQ, multi-select, open answer, true/false, match, order |
| LearnSpec-interoperable | Natively integrates with LearnMD, DiagramMD, MediaMD, GlossaryMD |
QuizMD inherits its frontmatter, directives, and validation rules from the shared Architecture Charter.
Format levels
| Level | Mechanism | Purpose |
|---|---|---|
| 0 | Plain .quiz.md, no configuration | Minimal quiz, human-readable |
| 1 | YAML frontmatter at top of file | Global metadata, behaviour, scoring |
| 2 | Per-question fenced block | Per-question overrides (points, timer, hint) |
Each level is a strict superset of the previous one.
Quick example
---
title: Physics Exam
lang: en
domain: academic
passing_score: 0.6
reveal: sequential
feedback_mode: deferred
spec_version: "0.3"
---
# Physics Exam
## Q1 · What is the speed of light in a vacuum?
- [ ] 150,000 km/s
- [x] 299,792 km/s
- [ ] 1,000,000 km/s
> The speed of light is c ≈ 2.998 × 10⁸ m/s.
## Q2 · State Newton's second law: F = ___.
**Answer:** ma
> F = ma: net force equals mass times acceleration.Try it
Open a real .quiz.md file in the player. It runs entirely in your browser, the file is fetched straight from GitHub, and nothing is uploaded anywhere.
Status
QuizMD is stable. v0.3 is drafting to align with the new LearnSpec suite, it requires the universal lang field, adds !ref for DiagramMD, MediaMD and GlossaryMD contexts, supports media:slug images with fallback URLs and ```diagram ref:slug for granular diagram reuse, and delegates diagram syntax to DiagramMD.
Next steps
- Read the full Specification.
- Try the Getting Started guide.
- Browse Examples.