Documentation

Complete guide to using the MCQ Examination Platform

Quick Start

  1. Upload your exam file (JSON, YAML, or Markdown format)
  2. Review the exam details and click "Start Exam"
  3. Answer questions at your own pace
  4. Submit when complete to see your results

Supported File Formats

JSON
Legacy format

Use for existing files. Not recommended for new exams due to escaping complexity.

YAML
Recommended

Best for programming exams. Clean syntax, no quote escaping, supports multi-line code.

Markdown
Most readable

Human-friendly format. Native code blocks, easy to write and preview.

File Structure

Required Fields

Exam Metadata

  • title - Exam name
  • duration - Time in minutes (YAML/MD) or seconds (JSON)
  • passingPercentage - Minimum score to pass (optional, default: 60)

Question Fields

  • id - Unique identifier
  • type - "single" or "multiple"
  • question - Question text
  • code - Code snippet (optional)
  • language - Programming language (optional, default: python)
  • options - Array of answer choices
  • correctAnswer - Index for single choice (0, 1, 2...)
  • correctAnswers - Array of indices for multiple choice
  • marks - Points for this question
  • explanation - Answer explanation

YAML Format Example

title: "Python Programming Exam"
duration: 60  # minutes
passingPercentage: 60

questions:
  - id: Q1
    type: single
    marks: 3
    question: "What will this code print?"
    code: |
      name = "World"
      print(f"Hello, {name}!")
    language: python
    options:
      - "Hello, World!"
      - "Hello, name!"
      - "name World"
      - "Error"
    correctAnswer: 0
    explanation: "F-strings substitute variables into the string."

Important Notes

Question Types

Only single and multiple types are supported. Matching, true/false, and other types are not currently available.

Code Formatting in YAML

When using code: | syntax in YAML:

  • NEVER escape quotes with backslashes
  • Paste code exactly as you would write it in a .py file
  • Use normal quotes: "text" not \"text\"
Answer Indexing

Answers use zero-based indexing. The first option is 0, second is 1, etc.

For multiple choice: correctAnswers: [0, 2, 3]

Using AI to Generate Exams

On the home page, you'll find AI-optimized prompts for popular AI assistants (Gemini, ChatGPT, Claude, Perplexity). These prompts help generate properly formatted YAML files.

Steps:

  1. Copy the prompt for your preferred AI
  2. Paste it into the AI chatbot along with your questions
  3. Copy the generated YAML output
  4. Save it as a .yaml file
  5. Upload to this platform

Platform Features

Syntax Highlighting
Code snippets are displayed with proper syntax highlighting for Python, JavaScript, Java, and 100+ other languages.
Question Navigator
Visual grid showing all questions with status indicators (current, answered, unanswered).
Progress Tracking
Real-time progress bar showing completion percentage and answered question count.
Timer
Countdown timer with auto-submit when time expires. Shows remaining time in MM:SS format.
Detailed Results
After submission, see your score, correct answers, and detailed explanations for each question.
Dark Mode
Automatic dark mode support with properly themed syntax highlighting.

Troubleshooting

File won't upload

Check the error message. Common issues: missing required fields (title, duration, questions), wrong question type, or malformed YAML/JSON syntax.

Code showing backslashes

Remove escape characters from your YAML. When using code: |, paste code normally without escaping quotes.

Timer not working

Ensure duration is set correctly. In YAML/Markdown, use minutes. In JSON, use seconds.

Sample Files

Example exam files are available in the public folder:

  • sample-exam.yaml - YAML format example
  • sample-exam.json - JSON format example
  • sample-exam.md - Markdown format example