How to add a quiz to your workshop
Tag a step `#[quiz]` and its body is parsed as a graded quiz instead of content. Each `##` heading inside it is a question, and GitHub task-list items are the options — `- [x]` marks a correct answer. Single- versus multiple-answer is inferred from how many options you mark correct, so there is nothing else to configure, and the correct-answer markers are stripped server-side before the step reaches a participant.
Last updated
Marking a step as a quiz
The marker rides on the heading line: `#[quiz]` followed by the quiz title. It replaces the usual `# Title` form for that step. The marker survives export, so a quiz round-trips through the single Markdown document like any other step.
#[quiz] Check your understanding
A short intro shown above the questions.
## What does `git rebase` do?
- [ ] Deletes the branch
- [x] Replays commits onto a new base
- [ ] Pushes to the remote
## Which of these are branching commands?
- [x] git switch
- [x] git checkout
- [ ] git commitSingle or multiple choice is inferred
Mark one option `[x]` and the question is single-answer. Mark two or more and it becomes multiple-answer. There is no `type:` line to write and no setting to forget — the answer key and the question type are the same piece of information.
Answers are hidden from participants
The server rewrites `- [x]` to `- [ ]` before quiz markdown is sent to anyone who is not the host. The participant's browser runs the same parser on a payload that genuinely has no answer key in it, rather than being trusted to hide one it received — a student reading the network response finds nothing to read.
Results are shown immediately or held until the host publishes them, per the session's configuration.
Authoring mistakes are surfaced, not fatal
Quiz parsing is deliberately tolerant: a question with no options, or a block that is not quite right, produces a warning for you as the author instead of an error for the room. A malformed quiz shows you a notice in the editor; it never takes a live session down.
Where quizzes fit
Quizzes are a step type inside a workshop, not the product. There are no speed points, streaks or leaderboards — grading is correctness-based. If you want a competitive quiz game, a dedicated quiz-game tool is the better shape; if you want a knowledge check inside a hands-on session, this is it.
Frequently asked questions
How many questions can one quiz step hold?
As many `##` headings as you write. Splitting a long quiz across several `#[quiz]` steps usually reads better and gives you per-step progress data.
Can I write open-text questions?
Not in a quiz step — quiz options are task-list items, so questions are single- or multiple-choice. For open responses, use a content step and the chat or inline annotations, or a broadcast.
Are quiz results in the session report?
Yes. Responses are recorded per participant and appear in the post-session report alongside progress and broadcast results, and the report exports as Markdown.
Can an AI write the quiz for me?
Yes, and this is the reason the format is plain text. Ask for questions as `##` headings with `- [ ]` / `- [x]` options, paste the result into the step, and it parses. No API, no schema, no import step.
Keep reading
How to write a workshop in Markdown
The complete authoring format: how # headings become steps, what Markdown is supported, and how to import or export a single .md file.
How to run your first live session
From a Markdown file to a running session: starting it, how participants join with a 6-character code, and pacing the room.
How to track participant progress in real time
How the per-step status model works — in progress, done and stuck — and how the dashboard turns it into a live view of who needs help.
Run your next workshop with the room visible.
Set up your first workshop in minutes — free, no credit card.