QuizPort for Obsidian

Run interactive quizzes inside your notes. Quizzes are plain JSON in the QuizPort format, so the same file works here and on quizport.io — no conversion, no lock-in.

• Answer questions inline in reading view, with scoring and instant feedback
• Explanations and hints shown at the right moment (hint before you answer, explanation after)
• Four question types: single choice, true/false, multi-select, and typed open response
• End-of-quiz review of what you missed, and a one-click retry of just the missed questions
• Shuffle mode randomises question and answer order
• Works offline, on desktop and mobile. Nothing leaves your vault.

Usage

A quiz inside a note

Put the JSON in a quizport code block:

```quizport
{
  "title": "Capitals",
  "questions": [
    {
      "question": "What is the capital of France?",
      "choices": ["London", "Paris", "Berlin", "Madrid"],
      "answer": 1,
      "explanation": "Paris has been the capital since 987 AD.",
      "hint": "It is on the Seine."
    }
  ]
}
```

Switch to reading view and the quiz becomes interactive.

The Insert quiz template command drops a working block in for you.

A quiz stored as its own file

Keep the JSON as a real .json file in your vault and point at it. This is the better option for anything you reuse, and it means a file downloaded from the QuizPort library works untouched:

```quizport
file: quizzes/security-plus.json
shuffle: true
```

The path resolves like an Obsidian link, so it can be relative to the note.

A quiz in its own tab

Open a .json quiz (or a note containing a quizport block) and run Run quiz from active file, or click the ribbon icon.

Quiz format

The minimum is a title and some questions:

{
  "title": "My Quiz",
  "questions": [
    { "question": "2 + 2 = ?", "choices": ["3", "4", "5"], "answer": 1 }
  ]
}

Everything else is optional. answer is a 0-based index into choices.

Field	Where	Notes
title	quiz	Required
description, category, difficulty, author, tags	quiz	Shown as badges
question	question	Required
choices	question	Required except for typed answers
answer	question	Index, list of indices, or literal text
explanation	question	Shown after answering
hint	question	Offered before answering
acceptable	question	Extra accepted spellings for typed answers

Question types

The type is inferred from the shape, so you never have to declare it and existing quizzes keep working:

{ "question": "Pick one",   "choices": ["a", "b"],      "answer": 0 }
{ "question": "True/false", "choices": ["True","False"],"answer": 1 }
{ "question": "Pick many",  "choices": ["a","b","c"],   "answer": [0, 2] }
{ "question": "Type it",    "answer": "Paris", "acceptable": ["Paris, France"] }

Typed answers are matched leniently — case, surrounding whitespace and a trailing ./!/? are ignored, so paris. matches Paris.

Settings

Setting	Default
Shuffle by default	Off	Randomise question and answer order
Instant feedback	On	Reveal correctness and the explanation after each answer
Keep attempt history	On	Store scores locally so you can export them

Export attempt history to a note writes a summary table plus the raw JSON into your vault.

Install

From the community plugins browser

Search for QuizPort in Settings → Community plugins. (Pending review — see "Status" below.)

Manually

1. Download main.js, manifest.json and styles.css from the latest release.
2. Put them in <vault>/.obsidian/plugins/quizport/.
3. Enable QuizPort in Settings → Community plugins.

Status

Version 0.3.0. Submitted to the community directory; awaiting review.

Requires Obsidian 1.13.0 or later. The settings tab uses the declarative settings API introduced in 1.13, which is also what makes QuizPort's settings findable from Obsidian's global settings search.

Development

npm install
npm run dev     # watch build
npm run build   # type-check and produce main.js

src/quizSchema.ts is a port of the quizport.io web app's schema module. The two are verified to produce identical results — normalization, canonical export, and scoring — against every quiz in the public library. The JSON Schema is the source of truth for the format; if you change one implementation, change both.

Privacy

Everything runs locally. The plugin makes no network requests: quizzes are read from your vault, and scores are stored in the plugin's own data file.

License

MIT