Create & Share Your Own Quiz

QuizPlay automatically discovers community quizzes from GitHub. Create a public repo, add your questions, and your quiz shows up for everyone — no pull request or approval needed. Quizzes can be about anything: Azure certifications, AWS, programming languages, history, science — you name it.

How It Works

QuizPlay searches GitHub for any public repository tagged with the quizplay topic. If your repo has a valid quiz.json at the root, it shows up in the Community Quizzes tab. QuizPlay pulls the title, description, and preview image from your quiz.json to build the card. When you update your repo, the changes are reflected automatically — there's nothing else to configure or deploy.

Quick Start — Use the Sample Repo

The fastest way to get started is to fork the sample quiz repository. It already has the correct structure, a working quiz.json, and example questions for every question type — so you can just swap in your own content.

Fork the sample repo — go to quizplay-io/quiz-player-sample-quiz and click the Fork button in the top right. This creates a copy under your own GitHub account (e.g. your-username/quiz-player-sample-quiz). You can rename it to anything you like.
Edit the files — you can either clone the repo locally and edit with your favourite editor, or edit the files directly on GitHub by clicking any file and then the pencil icon.

Open quiz.json and update it with your quiz's title, description, and question paths. See the full manifest reference for all available fields.

{
  "title": "Your Quiz Title",
  "description": "A short description for the quiz card.",
  "category": "Your Topic",
  "questions": [
    "questions/01-your-first-question.json",
    "questions/02-your-second-question.json"
  ]
}

Replace the sample questions in the questions/ folder with your own. Each question is a JSON file — see the question type reference below for all formats. You can delete the sample files you don't need.
Test locally (recommended) — go to quizplay.io, click the folder icon (Load from Local Folder), and select your quiz folder. This lets you play through the entire quiz to check for errors before publishing.
Add the quizplay topic — this is the critical step that makes your quiz discoverable. On your repo's GitHub page, click the gear icon next to "About" (top right of the repo), type quizplay in the Topics field, and click Save changes. Without this topic, QuizPlay won't find your repo.
That's it! Your quiz will appear in the Community Quizzes tab automatically. It may take a few minutes for GitHub's search index to pick it up. Any future changes you push to the repo will be reflected automatically.

Starting from Scratch

If you'd prefer to build your repo from the ground up instead of forking the sample, create a new public repository on your GitHub account, add a quiz.json manifest at the root and your question files, then add the quizplay topic. The full format for the manifest, question types, images, and case studies is covered below.

Repository Structure

Your repository should follow this layout:

my-quiz-repo/
├── quiz.json                  ← manifest (required)
├── questions/
│   ├── 01-first-question.json
│   ├── 02-second-question.json
│   └── ...
├── scenarios/                 ← case study files (optional)
│   └── scenario-a.json
└── assets/                    ← images (optional)
    └── images/
        └── diagram.png

The Manifest — `quiz.json`

Every quiz repo needs a quiz.json at the root. This tells QuizPlay what your quiz is about and where the questions live.

{
  "title": "My Awesome Quiz",
  "description": "A short description shown on the quiz card.",
  "slug": "my-awesome-quiz",
  "category": "General",
  "preview_image": "assets/images/preview.png",
  "questions": [
    "questions/01-first-question.json",
    "questions/02-second-question.json"
  ]
}

Field	Required	Description
`title`	Yes	Display name of your quiz
`questions`	Yes	Array of relative paths to question JSON files
`description`	No	Short description shown on the quiz card
`slug`	No	URL-friendly identifier (auto-generated from title if omitted)
`category`	No	Default category for questions that don't specify one
`preview_image`	No	Relative path or URL to a preview image for the quiz card

Question Types

QuizPlay supports seven question types. Each question is its own JSON file.

Single Choice single

One correct answer from a list of options. This is the default — if you omit the type field entirely, QuizPlay treats it as single choice.

{
  "id": "q-001",
  "type": "single",
  "question": "What does HTML stand for?",
  "options": [
    { "text": "Hyper Text Markup Language", "correct": true },
    { "text": "High Tech Modern Language" },
    { "text": "Hyper Transfer Markup Language" },
    { "text": "Home Tool Markup Language" }
  ],
  "explanation": "HTML stands for **Hyper Text Markup Language**.",
  "category": "Web Basics"
}

Multiple Choice multi

Multiple correct answers. The player shows "Select all that apply."

{
  "id": "q-002",
  "type": "multi",
  "question": "Which of the following are JavaScript data types?",
  "options": [
    { "text": "String", "correct": true },
    { "text": "Boolean", "correct": true },
    { "text": "Character" },
    { "text": "Number", "correct": true },
    { "text": "Integer" }
  ],
  "explanation": "JavaScript has String, Boolean, and Number as primitive data types."
}

Ordering ordering

Drag-and-drop to arrange items in the correct order. correctOrder is an array of zero-based indices representing the correct sequence.

{
  "id": "q-003",
  "type": "ordering",
  "question": "Arrange these steps in order:",
  "options": [
    { "text": "DNS Resolution" },
    { "text": "TCP Handshake" },
    { "text": "Send HTTP Request" },
    { "text": "Receive Response" },
    { "text": "Render Page" }
  ],
  "correctOrder": [0, 1, 2, 3, 4],
  "explanation": "The HTTP lifecycle starts with DNS, then TCP, request, response, render."
}

Hotspot hotspot

Click on the correct region of an image. Zone coordinates are percentages of image width/height. correctZone is the zero-based index of the correct zone.

{
  "id": "q-004",
  "type": "hotspot",
  "question": "Click on the Load Balancer in the diagram.",
  "image": "assets/images/architecture.png",
  "zones": [
    { "x": 10, "y": 5, "width": 25, "height": 20, "label": "Load Balancer" },
    { "x": 40, "y": 30, "width": 20, "height": 25, "label": "Web Server" },
    { "x": 70, "y": 50, "width": 20, "height": 20, "label": "Database" }
  ],
  "correctZone": 0,
  "explanation": "The Load Balancer sits at the entry point of the architecture."
}

Hotspot Dropdown hotspot-dropdown

Select the correct option from dropdown menus for each row.

{
  "id": "q-005",
  "type": "hotspot-dropdown",
  "question": "For each statement, select Yes if true or No if false.",
  "dropdowns": [
    {
      "label": "Azure Functions supports Python",
      "options": ["Yes", "No"],
      "correctIndex": 0
    },
    {
      "label": "Azure Functions requires a VM",
      "options": ["Yes", "No"],
      "correctIndex": 1
    }
  ],
  "explanation": "Azure Functions supports Python and is serverless."
}

Matching matching

Drag source items to the correct target slots. correctMapping[i] is the index into sourceItems that belongs in targetSlots[i].

{
  "id": "q-006",
  "type": "matching",
  "question": "Match each service to its purpose.",
  "sourceItems": [
    "Azure Blob Storage",
    "Azure SQL Database",
    "Azure Functions"
  ],
  "targetSlots": [
    "Object/file storage",
    "Relational database",
    "Serverless compute"
  ],
  "correctMapping": [0, 1, 2],
  "explanation": "Blob = files, SQL = relational, Functions = serverless."
}

Fill in the Blank fill-blank

Select the correct answer for each blank from a dropdown.

{
  "id": "q-007",
  "type": "fill-blank",
  "question": "Azure _____ is a managed NoSQL database, while Azure _____ is relational.",
  "blanks": [
    {
      "id": "blank-1",
      "label": "First blank",
      "options": ["Cosmos DB", "SQL Database", "Table Storage"],
      "correctIndex": 0
    },
    {
      "id": "blank-2",
      "label": "Second blank",
      "options": ["Cosmos DB", "SQL Database", "Table Storage"],
      "correctIndex": 1
    }
  ],
  "explanation": "Cosmos DB is NoSQL, SQL Database is relational."
}

Adding Images

Reference images using relative paths from your repo root:

{ "image": "assets/images/diagram.png" }

Or use absolute URLs:

{ "image": "https://example.com/images/diagram.png" }

Markdown image syntax also works inside question and explanation fields:

![Architecture](assets/images/arch.png)

Case Studies (Scenarios)

For multi-question case studies, create a shared scenario file and reference it with the caseStudy field. The scenario tabs appear alongside the question so the user can switch between context and the question.

Scenario file — scenarios/cloud-migration.json:

{
  "tabs": [
    {
      "title": "Overview",
      "content": "Contoso Ltd is migrating to Azure..."
    },
    {
      "title": "Requirements",
      "content": "- High availability across two regions\n- Budget: $5,000/month"
    }
  ]
}

Question file — references the scenario:

{
  "id": "migration-q1",
  "type": "single",
  "caseStudy": "scenarios/cloud-migration.json",
  "question": "Which service meets Contoso's HA requirement?",
  "options": [
    { "text": "Azure Traffic Manager", "correct": true },
    { "text": "Azure Load Balancer" },
    { "text": "Azure Application Gateway" }
  ],
  "explanation": "Traffic Manager provides DNS-based global load balancing."
}

Tips for a Great Quiz

Give each question a unique id — this powers progress tracking for anyone taking your quiz.

Write clear explanations — this is what helps people learn, not just the question itself.

Use Markdown in question and explanation fields — bold, code blocks, links, and images all work.

Add a preview_image to your quiz.json — it makes your quiz card stand out in the storefront.

Test locally first — use the folder icon on quizplay.io to load your quiz folder directly from your computer before publishing.

Check the sample quiz repo for a working example of every question type.

Publishing Checklist

quiz.json exists at the repo root with title and questions All question files referenced in quiz.json exist and are valid JSON Each question has at least a question field and answer data Repository is public Repository has the quizplay topic Tested locally using the "Load from Local Folder" button