YAML-Frontmatter Quizzes for Engineers

Why Frontmatter?

Most course platforms treat quizzes as a separate content type — you build them in a drag-and-drop UI, they live in a different database table, and they require their own API calls.

TeachRepo takes a different approach: quizzes are just YAML inside your lesson file. Same repo, same commit, same review process. If a quiz answer is wrong, you open a PR.

The Schema

Here's a complete lesson with a quiz:

---
title: "Git Rebase: The Complete Picture"
access: paid
quiz:
  - q: "What does `git rebase main` do when run from a feature branch?"
    options:
      - "Merges main into your feature branch, creating a merge commit"
      - "Replays your feature branch commits on top of main"
      - "Pushes your branch to origin/main"
      - "Creates a new branch from main"
    answer: "Replays your feature branch commits on top of main"
    explanation: |
      Rebase replays your commits on top of the target branch, producing
      a linear history. Unlike merge, it rewrites commit hashes.

  - q: "When should you prefer rebase over merge?"
    options:
      - "Always — rebase is strictly better"
      - "Never — rebase rewrites history and is dangerous"
      - "For local cleanup before sharing; avoid on shared branches"
      - "Only for squashing commits"
    answer: "For local cleanup before sharing; avoid on shared branches"
    explanation: |
      Rebase is great for tidying up local work before a PR review.
      On shared branches (main, develop), force-pushing rebased commits
      breaks everyone else's checkout.
---

# Git Rebase: The Complete Picture

Lesson content here...

How Grading Works

When a student submits a quiz, TeachRepo grades it client-side:

1. The lesson page is rendered with quiz data embedded in the HTML (at build time)
2. Student selects answers and clicks "Submit Quiz"
3. JavaScript compares selected answers against the correct answers (already in the DOM)
4. Score is computed; feedback is shown immediately
5. A non-blocking quiz_submitted event is sent to the analytics endpoint

No server round-trip. No database write on the critical path. Quiz results appear in <50ms regardless of network conditions.

The Quiz Component

TeachRepo's Quiz component is a straightforward React state machine:

// Simplified quiz state
type QuizState = 'unanswered' | 'submitted';

// Each question tracks:
// - selected: string | null  (the chosen option)
// - correct: boolean | null  (null until submitted)

// On submit:
const grade = (questions: Question[], answers: Record<number, string>) => {
  return questions.map((q, i) => ({
    ...q,
    selectedAnswer: answers[i] ?? null,
    correct: answers[i] === q.answer,
  }));
};

// Score is just:
const score = graded.filter(q => q.correct).length;
const pct = Math.round((score / total) * 100);

After submission, correct answers turn green with an explanation, wrong answers turn red. The student can see exactly where they went wrong without any server involvement.

Security: Can Students Cheat?

Yes — a determined student can read the correct answers from the page source. This is an intentional tradeoff. Here's the reasoning:

• These are learning quizzes, not certification exams. The goal is to reinforce understanding, not gatekeep credentials.
• Hiding answers requires a backend round-trip, which adds latency, complexity, and cost — not worth it for learning reinforcement.
• Students who cheat only hurt themselves. If they skip the quiz to unlock the next lesson, they miss the learning feedback loop.

If you need tamper-proof quiz scoring (e.g., for certifications), that's a different product. For technical courses, the fast client-side UX wins.

Explanation Fields

Every quiz option can have an explanation field. After submission, the explanation for the correct answer is shown regardless of whether the student got it right.

This is the most valuable part of the quiz. A good explanation:

• Reinforces why the answer is correct
• Points to relevant documentation or concepts
• Preemptively addresses common misconceptions

quiz:
  - q: "What's the time complexity of `git log --oneline`?"
    options:
      - "O(1)"
      - "O(log n) where n = number of commits"
      - "O(n) where n = number of commits"
      - "O(n²) due to graph traversal"
    answer: "O(n) where n = number of commits"
    explanation: |
      git log traverses the commit DAG from HEAD, visiting each commit
      once. With --oneline it outputs one line per commit but still
      traverses the full history unless you specify --max-count or a
      revision range. Use `git log --oneline -20` to limit output.

Analytics

TeachRepo fires a non-blocking quiz_submitted event to POST /api/events after each submission. This writes asynchronously to Supabase and shows in your creator dashboard:

• Average score per quiz
• Most-missed questions (useful for improving lesson content)
• Completion rate (students who submitted vs. students who viewed)

Editing Quizzes

Editing a quiz is as simple as editing a .md file:

# Fix a typo in a quiz option:
git checkout -b fix/quiz-typo
# Edit the .md file
git add lessons/03-advanced.md
git commit -m "fix: correct typo in quiz option 2"
git push

# CI validates the YAML + answer keys, then deploys.
# Done.