A plugin to create interactive quizzes directly in your Starlight or plain Astro markdown documentation. Perfect for educational content, tutorials, and documentation that requires reader engagement.

Features

• ✨ Simple markdown syntax - write quizzes with GitHub-flavoured task lists, no new syntax to learn
• 🎯 Multiple quiz types - single choice (radio), multiple choice (checkboxes), and fill-in-the-blank
• ⚡ Instant feedback - per-answer feedback and visual correct/incorrect indicators
• 📝 Rich explanations - reveal a markdown content section after answering, with code blocks, tables and images
• 📊 Progress & results - an aggregate results panel with score tiers and confetti 🎉
• 💾 Results saved - answers persist to the browser's local storage, surviving reloads and rebuilds
• 🔀 Author controls - shuffle answers, auto-number questions, and set site-wide behaviour defaults
• 🌐 Internationalisation - 13 languages out of the box (shared with mkdocs-quiz), with label props otherwise
• 🧩 Works anywhere - a zero-config Starlight plugin or standalone in any Astro project, safe under view transitions
• ♿ Accessible - real fieldsets, aria-live feedback, focus management and keyboard-safe auto-submit
• 📤 LMS export - emit a quiz manifest and export to QTI 1.2/2.1 for Canvas, Moodle and Blackboard
• 🖥️ Terminal runner - take quizzes in your terminal, from a local build or a deployed site

import { Quiz } from 'starlight-quiz/components';

<Quiz title="Static site generators">
Which of these are static site generators?

- [x] Astro
- [ ] Django
- [x] Eleventy

Astro and Eleventy build static sites, while Django is a web framework.

</Quiz>

Installation

npm install starlight-quiz

Usage

As a Starlight plugin (zero config)

Add the plugin to your Starlight configuration — it wires up the styles and translations for you:

// astro.config.mjs
import starlight from '@astrojs/starlight';
import starlightQuiz from 'starlight-quiz';
import { defineConfig } from 'astro/config';

export default defineConfig({
  integrations: [
    starlight({
      title: 'My docs',
      plugins: [starlightQuiz()],
    }),
  ],
});

Then import the components in any .mdx page and author your quiz with markdown:

import { Quiz, QuizResults } from 'starlight-quiz/components';

<Quiz title="Primary colours">
Which of these are primary colours?

- [x] Red
- [ ] Green
  > Green is a secondary colour.
- [x] Blue

Primary colours cannot be made by mixing other colours.

</Quiz>

<Quiz title="Cell biology">
The powerhouse of the cell is the [[mitochondria]].
</Quiz>

<QuizResults confetti />

Standalone in any Astro project

The components have no hard dependency on Starlight. Import them the same way and the stylesheet yourself, passing label props for any text you want to translate:

---
import { Quiz } from 'starlight-quiz/components';
import 'starlight-quiz/styles';
---

<Quiz title="Quick check" submitLabel="Check answer">
Is the sky blue?

- [x] Yes
- [ ] No
</Quiz>

Documentation

Full guides, the authoring reference and a live demo are on the documentation site.

License

This project is licensed under the Apache License 2.0.

Credits

• Created by Phil Ewels
• Ported from mkdocs-quiz, originally by Sebastian Jörz before being rewritten by Phil Ewels.

Tip

Writing docs with MkDocs instead?
Try mkdocs-quiz, which brings the same markdown quiz syntax to MkDocs and Material for MkDocs.