CQuiz

A powerful, feature-rich quiz engine for Obsidian that turns your markdown notes into interactive exams.

Author: carbon-softlab
Version: 1.0.0 Repository: https://github.com/carbon-softlab/CQuiz

Table of Contents

• Installation
• Quick Start
• Question Format
• Block API Reference
• Scoring & Formulas
• Render Styles
• Tag System
• Spaced Repetition
• Analytics Dashboard
• Export to Note
• Strict Mode
• Settings
• Keyboard Shortcuts

Installation

1. Download main.js and manifest.json from the repository.
2. In your vault, create the folder .obsidian/plugins/cquiz/.
3. Place both files inside that folder.
4. Open Obsidian → Settings → Community Plugins → enable CQuiz.

Quick-Start

Create a cquiz code block anywhere in a markdown note:

```cquiz
@name= My First Quiz
@Set= (MyNotes)
@passMark= 5
```

This loads all questions from the note MyNotes.md and presents an interactive quiz. Click Start Quiz to begin.

Question-Format

Questions are written in standard markdown checkbox list format inside any .md file.

1. [ ] What is the capital of France?
    1. [ ] London
    2. [x] Paris
    3. [ ] Berlin
    4. [ ] Madrid

2. [ ] Which of these are prime numbers? (select all)
    1. [x] 2
    2. [ ] 4
    3. [x] 7
    4. [x] 11
> [!NOTE] A prime number is divisible only by 1 and itself.

3. [x] This question has already been read/studied.
    1. [x] Correct option
    2. [ ] Wrong option

Rules

Block-API-Reference

All options are written as @key= value inside a cquiz block. Keys are case-insensitive.

Source Options

Exam-Options

Full-Example

```cquiz
@name= Biology Final — Chapter 4-6
@Show= 45 minutes. Covers cell division and genetics.
@SetAll= (Biology/Chapter4, Biology/Chapter5, Biology/Chapter6)
@Random= true
@Limit= 40
@Duration= 45m
@PassMark= 50
@PauseButton= true
@RenderStyle= paged
@Formula = ({correct}*1-{wrong}*1)
```

Scoring-&-Formulas

The default scoring formula is:

({correct} * @markPerQ) - ({wrong} * @penalty)

You can write any custom formula using these variables:

Formula-Functions

IF(condition, trueValue, falseValue), pow(base, exp), sqrt(x), nroot(x, n), mod(a, b)

Custom-Formula-Examples

# Standard with penalty
@Formula= ({correct} * @markPerQ) - ({wrong} * @penalty)

# Percentage score
@Formula= ({correct} / {total}) * 100

# Bonus for no skips
@Formula= ({correct} * 2) + IF({skip} == 0, 10, 0)

# Only penalise after 3 wrong answers
@Formula= ({correct} * @markPerQ) - IF({wrong} > 3, ({wrong} - 3) * @penalty, 0)

Render-Styles

Scroll Mode (default)

All questions appear in a single scrollable list. A sticky progress bar and submit bar stay visible at the bottom.

@RenderStyle= scroll

Paged-Mode

One question per screen with navigation controls.

@RenderStyle= paged

Navigation:

• ← / → arrow buttons
• Dot indicators — click any dot to jump directly to that question. Dots turn accent-coloured when answered.
• Keyboard: Alt + ← / Alt + → (desktop)
• Skipped question numbers in the submit bar are clickable — jump directly to that page

Tag-System

Tags let you categorise questions as Hard, Medium, Easy, Hint, or any custom label. Tagged questions can be used as a source for future quizzes.

Tagging a question during a quiz

Each question card has a tag bar. Click any tag pill to apply it — the pill fills with the tag colour. Click again to remove it. Changes save instantly to the vault.

• Inactive hover → previews what the tag will look like when applied
• Active hover → dims the pill to preview removal

Using tagged questions as a source

@SetType= Hard, Medium

Loads only questions you've previously tagged as Hard or Medium, regardless of which note they're in.

Managing tags

Open the Analytics Dashboard (@Mode= stats) → Manage Tags & Saved Questions to:

• Rename or delete tags
• Browse all questions under a tag
• Add custom tags

Spaced-Repetition

CQuiz includes an SM-2-based spaced repetition system. Enable it with:

@Repetition= 5

The value (0–10) controls how strongly overdue and difficult questions are prioritised. Questions are scored by:

• Overdue ratio (how many days past the review date)
• Mastery rate (correct ÷ total attempts)
• Streak (consecutive correct answers)

After each exam, review intervals are updated automatically. The next review date is calculated using the SM-2 ease factor.

Reset repetition data: Settings → Reset Rep Data

Analytic-Dashboard

Add a stats block anywhere in your vault:

```cquiz
@Mode= stats
```

Overview-Tab

• Total exams taken, average score, best/worst accuracy
• Bar chart of accuracy per exam (last 10)
• Quick access to Tag Manager

History-Tab

A full table of every exam with:

• Date, exam name, pass/fail badge, score, correct/wrong/skipped, accuracy bar, time taken
• 👁 View — re-read the full question review for any past exam
• 📋 Export — export any past exam result to a markdown note
• 🗑 Delete — remove individual records
• Search, status filter (all/pass/fail), and sort (newest/oldest/best/worst)

Export-to+Note

After finishing an exam, click Export to Note on the results screen. A markdown note is created in your configured export folder (default: CQuiz-Results/) and opened in a new tab.

Exported-format

# 📋 Exam Results: Biology Final

> **Date:** 13/06/2026, 14:32
> **Result:** ✅ PASSED
> **Score:** 38 / 50
> **Pass Mark:** 30

## 📊 Summary

| Metric | Value |
|--------|-------|
| Final Score | 38 / 50 |
| Correct | 19 |
...

## 🗒️ Question Review

1. [x] What is mitosis?
#hard
%%status: correct ✅%%
    1. [ ] Cell death
    2. [x] Cell division producing identical daughter cells
    3. [ ] DNA replication only

Each question uses the native CQuiz format so notes can be re-imported or studied later. Wrong answers are annotated with ← *your answer*.

Strict-Mode

@Strict= true

Locks the current note for the duration of the exam. If you navigate to another note, Obsidian jumps you back and shows a warning. The lock is released when you submit or pause the exam.

Settings

Open Settings → CQuiz to configure:

📁 Export Settings

Click 📂 Open in Explorer to reveal the folder in Obsidian's file explorer. A live path hint (→ vault/CQuiz-Results/) updates as you type.

⚙️ General

⚠️ Danger-Zone

Keyboard-Shortcuts

Question-File-Tips

• Questions from multiple files can be combined in one quiz using @Set= (File1, File2) or @SetAll= (FolderName)
• Images in questions and options are fully supported — click to expand in a lightbox
• Markdown (bold, italic, code blocks, LaTeX) renders everywhere
• Mark questions as read with [x] at the question level, then use @Filter= onlyread to quiz only studied material
• Use @StartFrom and @EndTo to slice a large question bank into sessions