Examark

Write exams in Markdown. Export to Canvas in seconds.

Documentation · Getting Started · Report Bug

---

Why Examark?

Stop clicking through Canvas forms. Write once, export anywhere.

┌─────────────────┐      ┌──────────┐      ┌─────────────────┐
│   quiz.md       │ ───▶ │ examark  │ ───▶ │  quiz.qti.zip   │
│   (Markdown)    │      │          │      │  (Canvas-ready) │
└─────────────────┘      └──────────┘      └─────────────────┘
                              │
                              ▼
                    ┌─────────────────┐
                    │   quiz.txt      │
                    │   (Printable)   │
                    └─────────────────┘

Perfect for: Instructors, TAs, and course developers who want version-controlled, portable exam files.

---

Quick Start

No installation needed — try it now:

npx examark quiz.md -o quiz.qti.zip

Write Your Exam

# Statistics Midterm

1. [MC] What is the mean of 2, 4, 6? [2pts]
a) Three
b) Four [x]
c) Five

2. [TF] Variance can be negative. [1pt]
a) True
b) False [x]

3. [Essay, 10pts] Explain the Central Limit Theorem.

Convert & Import

examark midterm.md -o midterm.qti.zip    # For Canvas
examark midterm.md -f text                # For printing

Then: Canvas → Settings → Import Content → QTI .zip

Or Import to Item Banks (New Quizzes)

For random question selection across quizzes:

1. Quizzes → ⋮ → Manage Item Banks
2. + Add Bank → Name your bank
3. ⋮ → Import Content → Upload .qti.zip
4. Create quiz → Add from Item Bank → Randomly select N questions

📖 Item Banks Tutorial →

---

Features

📝 Clean Syntax Write questions naturally without complex markup. 1. [MC] Question here [2pts] a) Wrong b) Right [x]	🧮 LaTeX Math Full equation support, auto-converted for Canvas. Find $\bar{x}$ given: $$\bar{x} = \frac{\sum x_i}{n}$$
📦 8 Question Types Multiple Choice ([MC]) True/False ([TF]) Multiple Answer ([MA]) Short Answer ([Short]) Numerical ([Num]) Essay ([Essay]) Matching ([Match]) Fill-in-Multiple-Blanks ([FMB])	🔧 Powerful CLI examark *.md -o output/ # Batch convert examark quiz.md -f text # Paper exams examark verify pkg --strict # New Quizzes check examark check quiz.md # Lint syntax
🖼️ Image Bundling Local images automatically packaged into QTI. 	🔬 Quarto Integration Dynamic questions with R/Python. format: exam-gfm exam: qti: true

---

Installation

🚀 Choose Your Path

📝 Markdown Only Write .md files → Canvas	📊 Quarto Only Author .qmd → HTML/PDF	📊🎯 Quarto + Canvas Author .qmd → Canvas
One-Line Install: npx examark quiz.md No install needed!	One-Line Install: quarto add Data-Wise/examark Extension only.	Two Steps: quarto add Data-Wise/examark npm install -g examark Extension + CLI.

---

📦 Detailed Installation Guide

⚡ One-Line (No Install) — Try It Now

For Markdown users who want to convert .md → QTI immediately:

npx examark quiz.md -o quiz.qti.zip

What this does:

• Downloads examark temporarily to npm cache
• Converts your markdown file to QTI
• No permanent installation

Requirements: Node.js ≥18 (see Windows/Mac setup below)

When to use: Quick one-off conversions, trying examark without committing

---

👤 Average User — Permanent Install

For Markdown Users (Static Exams)

Install once, use forever:

macOS:

# Option A: Homebrew (recommended)
brew install data-wise/tap/examark

# Option B: npm
npm install -g examark

Windows:

npm install -g examark

Linux:

npm install -g examark

Usage:

examark quiz.md -o quiz.qti.zip
examark *.md -o output/           # Batch convert

---

For Quarto Users (Preview Only - No QTI)

Install Quarto extension for authoring and preview:

quarto add Data-Wise/examark

What you get:

• Formats: exam-html, exam-pdf, exam-odt, exam-docx, exam-typst
• LaTeX math support
• Solution toggle (exam.solutions: true/false)

What you DON'T get: QTI conversion (see "Quarto + QTI" below)

Usage:

quarto render exam.qmd --to exam-html    # Preview in browser
quarto render exam.qmd --to exam-pdf     # Print version

---

For Quarto Users (Full Workflow - Preview + QTI)

Install both extension (authoring) and CLI (QTI conversion):

# Step 1: Quarto extension
quarto add Data-Wise/examark

# Step 2: CLI tool
npm install -g examark        # Windows/Linux
brew install data-wise/tap/examark  # macOS (alternative)

Complete workflow:

# 1. Author exam
vim exam.qmd

# 2. Render to markdown
quarto render exam.qmd --to exam-gfm

# 3. Convert to QTI
examark exam.md -o exam.qti.zip

# 4. Upload to Canvas
open exam.qti.zip  # Drag to Canvas → Import Content

💡 Tip: Use npx examark instead of installing globally if you prefer

---

🔰 First-Time Setup (Windows/Mac)

Windows Users

If you've never used Node.js:

1. Install Node.js → nodejs.org

   • Click green "LTS" button
   • Run installer, accept all defaults
   • Click through everything

2. Open Terminal:

   • Press Windows + R
   • Type cmd and press Enter

3. Test it works:

   node --version

   Should show: v18.x.x or higher

4. Use examark:

   npx examark quiz.md -o quiz.qti.zip

Permanent install:

npm install -g examark

---

macOS Users

Recommended: Homebrew (easiest)

1. Install Homebrew (if not installed):

   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

2. Install examark:

   brew install data-wise/tap/examark

Alternative: npm

1. Install Node.js → nodejs.org

2. Install examark:

   npm install -g examark

---

🛠️ Advanced Users

Install from Source

git clone https://github.com/Data-Wise/examark.git
cd examark
npm install
npm run build
npm link

Install Specific Version

npm install -g examark@0.7.0

Update to Latest

npm update -g examark       # npm
brew upgrade examark        # Homebrew

Uninstall

npm uninstall -g examark    # npm
brew uninstall examark      # Homebrew

---

Commands

Command	Description
examark <file.md>	Convert to QTI (default: file.qti.zip)
examark <file.md> -f text	Export as printable plain text
examark *.md -o output/	Batch convert multiple files
examark verify <pkg>	Validate QTI package
examark verify <pkg> --strict	Strict validation for New Quizzes
examark emulate-canvas <pkg>	Simulate Canvas import
examark check <file.md>	Lint markdown for errors
examark --preview	Preview parsed questions (JSON)

Options: -o <output> · -p <points> · -t <title> · --no-answers · -v · --strict

---

Configuration

Create .examarkrc.json for project defaults:

{
  "defaultPoints": 2,
  "outputDir": "output",
  "validate": true
}

---

Templates

Markdown (no Quarto needed):

Template	Description
minimal.md	3 questions — quickest start
starter.md	One of each question type
all-question-types.md	Comprehensive — all 8 types

Quarto (for R/Python users):

Template	Description
minimal.qmd	Simplest Quarto template
starter.qmd	Full-featured starter
dynamic.qmd	Randomized questions with R
with-figures.qmd	R-generated plots

---

Quarto Integration

Generate dynamic, randomized questions with R or Python code.

Quick Start

# Add extension to existing project
quarto add Data-Wise/examark

# Or start from template
quarto use template Data-Wise/examark

⚠️ Note: This only installs the Quarto extension (for authoring/preview). To export QTI packages, also install the CLI: npm install -g examark

Example: Dynamic Questions

---
title: "Statistics Exam"
format: exam-html      # Preview in browser
exam:
  solutions: false
  default-points: 1
---

## 1. Random Calculation [2pts]

What is `r x <- sample(1:10, 1); x` + `r y <- sample(1:10, 1); y`?

a) `r x + y - 2`
b) `r x + y` [x]
c) `r x + y + 2`

Available Formats

Format	Output	Use Case
exam-html	HTML	Browser preview
exam-pdf	PDF	Print exams
exam-gfm	Markdown	QTI conversion (use with CLI)
exam-odt	ODT	Google Docs, LibreOffice
exam-docx	DOCX	Microsoft Word
exam-typst	PDF	Modern typesetting

Complete QTI Workflow

# 1. Render to markdown
quarto render exam.qmd --to exam-gfm

# 2. Convert to QTI (requires CLI installed)
examark exam.md -o exam.qti.zip

# 3. Upload to Canvas

📖 Full Quarto Guide → · Dynamic Examples →

---

Claude Code Plugin

Use examark directly from Claude Code with slash commands.

Commands

Command	Description
/exam:convert <file>	Convert .md or .qmd to QTI package
/exam:check <file>	Lint markdown or verify QTI package
/exam:preview <file>	Show formatted question summary table

Auto-Lint Hook

The plugin includes a PostToolUse hook that automatically lints exam files after edits, catching errors as you write.

Installation

Copy or symlink the .claude-plugin/ directory and commands/ directory to use with Claude Code. The plugin also includes migrated skills for exam generation and formatting knowledge.

---

Documentation

📚 Full Docs	Complete reference
🚀 Getting Started	Install + first quiz
📝 Markdown Syntax	Question syntax
🏦 Item Banks	Random quizzes
⚙️ Configuration	Project settings
🎓 Tutorials	R/Quarto, VS Code

---

Get Started →

Made with ❤️ by Data-Wise · MIT License