gh-dnvriend-markdown-quiz-exporter-tool-plugins-markdown-quiz-exporter-tool/skills/markdown-quiz-exporter-tool/SKILL.md

name, description

name	description
skill-markdown-quiz-exporter-tool	Export quiz markdown to Anki, Flashcard Hero, HTML

When to use

• Export quiz markdown to flashcard formats (Anki, Flashcard Hero)
• Generate interactive HTML quiz pages
• Convert study materials to multiple formats

markdown-quiz-exporter-tool Skill

Purpose

The markdown-quiz-exporter-tool is a CLI tool that exports quiz markdown files to multiple formats including Anki CSV, Flashcard Hero TSV, and interactive HTML quiz pages. It supports single-choice and multiple-choice questions with explanations.

When to Use This Skill

Use this skill when:

• Converting quiz markdown to flashcard applications (Anki, Flashcard Hero)
• Generating self-contained HTML quiz pages with interactive features
• Exporting study materials to different formats for students
• Creating quiz applications with dark/light mode support
• Building responsive mobile-friendly quiz interfaces

Do NOT use this skill for:

• Creating the original quiz markdown content (use a text editor)
• Importing flashcards back to markdown format
• Modifying existing quiz content (edit the markdown directly)

CLI Tool: markdown-quiz-exporter-tool

A command-line utility for exporting quiz markdown files to multiple formats with comprehensive validation and error handling.

Installation

# Clone repository
git clone https://github.com/dnvriend/markdown-quiz-exporter-tool.git
cd markdown-quiz-exporter-tool

# Install with uv
uv tool install .

# Verify installation
markdown-quiz-exporter-tool --version

Prerequisites

• Python 3.14+
• uv package manager
• Quiz markdown files in the correct format

Quick Start

# Export to Flashcard Hero
markdown-quiz-exporter-tool flashhero quiz.md flashcards.tsv

# Export to Anki (quiz format)
markdown-quiz-exporter-tool anki quiz.md cards.csv

# Generate HTML quiz
markdown-quiz-exporter-tool quiz-html quiz.md quiz.html --title "My Quiz"

Progressive Disclosure

📖 Core Commands (Click to expand)

flashhero - Export to Flashcard Hero

Export quiz markdown to Flashcard Hero TSV format with tab-separated question/answer pairs.

Usage:

markdown-quiz-exporter-tool flashhero INPUT_FILE OUTPUT_FILE [OPTIONS]

Arguments:

• INPUT_FILE: Path to quiz markdown file (*.md)
• OUTPUT_FILE: Path where TSV file will be written (*.tsv)
• --force / -f: Overwrite output file if it exists
• -v/-vv/-vvv: Verbosity levels (INFO/DEBUG/TRACE)

Examples:

# Basic export
markdown-quiz-exporter-tool flashhero quiz.md flashcards.tsv

# Overwrite existing file
markdown-quiz-exporter-tool flashhero quiz.md flashcards.tsv --force

# With verbose output for debugging
markdown-quiz-exporter-tool flashhero quiz.md flashcards.tsv -vv

Output Format:

Question<TAB>Answer
Question<TAB>Answer1; Answer2; Answer3

For questions with multiple correct answers, they are joined with "; " separator.

---

anki - Export to Anki

Export quiz markdown to Anki CSV format supporting two note types: AllInOne (quiz) and Basic (recall).

Usage:

markdown-quiz-exporter-tool anki INPUT_FILE OUTPUT_FILE [OPTIONS]

Arguments:

• INPUT_FILE: Path to quiz markdown file (*.md)
• OUTPUT_FILE: Path where CSV file will be written (*.csv)
• --quiz: Export as AllInOne quiz format (default)
• --recall: Export as Basic recall format
• --force / -f: Overwrite output file if it exists
• -v/-vv/-vvv: Verbosity levels (INFO/DEBUG/TRACE)

Examples:

# Export as quiz format (default)
markdown-quiz-exporter-tool anki quiz.md quiz-cards.csv

# Export as recall format
markdown-quiz-exporter-tool anki quiz.md recall-cards.csv --recall

# Overwrite existing file
markdown-quiz-exporter-tool anki quiz.md cards.csv --force

# With verbose output
markdown-quiz-exporter-tool anki quiz.md cards.csv -vv

Output Formats:

AllInOne (--quiz):

Question;Title;QType;Q_1;Q_2;Q_3;Q_4;Q_5;Answers;Sources;Extra1;Tags

Basic (--recall):

Front;Back;Tags

Note: AllInOne format supports maximum 5 answer options. Questions with more than 5 options will have only the first 5 included.

---

quiz-html - Generate Interactive HTML Quiz

Generate self-contained HTML quiz page with embedded CSS, JavaScript, and quiz data.

Usage:

markdown-quiz-exporter-tool quiz-html INPUT_FILE OUTPUT_FILE --title "TITLE" [OPTIONS]

Arguments:

• INPUT_FILE: Path to quiz markdown file (*.md)
• OUTPUT_FILE: Path where HTML file will be written (*.html)
• --title "TITLE": Quiz title displayed on intro page (required)
• --force / -f: Overwrite output file if exists
• -v/-vv/-vvv: Verbosity levels (INFO/DEBUG/TRACE)

Examples:

# Generate quiz HTML
markdown-quiz-exporter-tool quiz-html quiz.md quiz.html --title "My Quiz"

# Overwrite existing file
markdown-quiz-exporter-tool quiz-html quiz.md quiz.html --title "Quiz" --force

# With verbose output
markdown-quiz-exporter-tool quiz-html quiz.md quiz.html --title "Quiz" -vv

Features:

• Dark/light mode with system preference detection and manual toggle
• Configurable question/answer shuffling on intro page
• Progress tracking with visual progress bar
• Timer tracking elapsed time
• Statistics page with score percentage and per-question review
• Review mode for detailed answer inspection
• Session storage for progress persistence across page refreshes
• Mobile-responsive design using Tailwind CSS
• Markdown rendering in explanation text
• Always-visible "Volgende" (Next) button for easy navigation
• Single self-contained HTML file (no external dependencies except Tailwind CDN)

Output: Self-contained HTML file (typically 30-50 KB) containing:

• Embedded quiz data (JSON)
• Embedded JavaScript quiz application
• Embedded CSS styling
• Tailwind CSS via CDN
• Marked.js for markdown rendering

📝 Quiz Markdown Format (Click to expand)

Format Specification

Quiz markdown files must follow this format:

Question text here?

- (X) Correct answer
- ( ) Wrong answer 1
- ( ) Wrong answer 2

# reason
Explanation text here with markdown support.
Can include **bold**, *italic*, and other markdown features.

---

Another question?

- [X] Correct answer 1
- [X] Correct answer 2
- [ ] Wrong answer

# reason
Explanation for multiple choice question.

---

Format Rules

1. Question Text: Plain text (no ## header needed)
2. Single Choice Answers: Use ( ) for incorrect, (X) for correct (radio buttons)
3. Multiple Choice Answers: Use [ ] for incorrect, [X] for correct (checkboxes)
4. Explanation: Use # reason header followed by explanation text
5. Separator: Use --- between questions
6. Question Types:
   • Single choice: Use ( ) and (X) notation
   • Multiple choice: Use [ ] and [X] notation

Category Extraction

Questions can include category prefixes (used by HTML quiz for badges):

CATEGORY: Question text?

This will:

• Extract "CATEGORY" as the category
• Display "Question text?" as the clean question text
• Show category badge in HTML quiz

Example:

S3: What is the max size of an S3 object in GB?

- ( ) 1000
- (X) 5000
- ( ) 10000

# reason
The maximum size is 5TB or 5000GB.

---

⚙️ Advanced Features (Click to expand)

HTML Quiz Interactive Features

Configuration Page:

• Shuffle questions checkbox
• Shuffle answers checkbox
• Auto-advance option (disabled by default)
• Auto-advance delay setting (1-10 seconds)

Question Page:

• Progress bar showing current question/total
• Category badge (if present)
• Radio buttons (single choice) or checkboxes (multiple choice)
• "Controleren" (Check) button
• "Volgende" (Next) button (always visible)
• "Vorige" (Previous) button (if not first question)
• Visual feedback: green for correct, red for incorrect
• Markdown-rendered explanation after checking

Statistics Page:

• Circular score percentage indicator
• Score fraction (correct/total)
• Time elapsed (MM:SS format)
• Status: Geslaagd (≥75%), Voldoende (≥50%), Onvoldoende (<50%)
• Clickable question list for review

Review Mode:

• Read-only view of questions
• All correct answers highlighted in green
• Incorrect selected answers highlighted in red
• Full explanation visible
• "Terug naar resultaten" (Back to results) button

Dark/Light Mode:

• Auto-detect system preference on load
• Manual toggle button (fixed top-right)
• Smooth transitions between modes
• Custom scrollbar styling for dark mode

State Persistence:

• Uses session storage (not local storage)
• Saves: current page, answers, checked status, config, timestamps
• Clears on browser close
• Persists on page refresh

Verbosity Levels

Control output detail with -v flags:

# Default: Warnings only
markdown-quiz-exporter-tool anki quiz.md output.csv

# INFO: High-level operations
markdown-quiz-exporter-tool anki quiz.md output.csv -v

# DEBUG: Detailed debugging
markdown-quiz-exporter-tool anki quiz.md output.csv -vv

# TRACE: Library internals
markdown-quiz-exporter-tool anki quiz.md output.csv -vvv

Force Overwrite

By default, commands fail if output file exists:

# Fails if output.csv exists
markdown-quiz-exporter-tool anki quiz.md output.csv

# Overwrites without confirmation
markdown-quiz-exporter-tool anki quiz.md output.csv --force

🔧 Troubleshooting (Click to expand)

Common Issues

Issue: "Error: Quiz file not found"

Error: Quiz file not found: quiz.md

Solution:

• Verify file path is correct
• Use absolute path if relative path fails
• Check file exists: ls -la quiz.md

---

Issue: "Error parsing quiz file"

Error parsing quiz file: Invalid question format

Solution:

• Verify markdown format follows specification
• Check for missing ## question headers
• Ensure answers use - [ ] or - [x] format
• Verify --- separators between questions
• Use -vv for detailed parse errors

---

Issue: "Output file already exists"

Error: Output file 'output.csv' already exists. Use --force to overwrite.

Solution:

• Add --force flag to overwrite
• Or delete existing file first
• Or use different output filename

---

Issue: "Questions exceed 5-option limit"

Warning: 3 question(s) have more than 5 answer options.
Only the first 5 will be included in AllInOne format.

Solution:

• This is expected for Anki AllInOne format (5 option limit)
• Options:
  1. Use Basic format: --recall
  2. Reduce answers to 5 per question
  3. Accept that only first 5 are exported

---

Issue: "HTML quiz not displaying correctly"

Symptoms:

• Layout broken
• Dark mode not working
• JavaScript errors

Solution:

• Verify file opened in modern browser (Chrome 90+, Firefox 88+, Safari 14+)
• Check browser console for JavaScript errors
• Ensure internet connection (Tailwind CDN required)
• Clear browser cache and reload
• Try opening in different browser

---

Issue: "Markdown not rendering in quiz explanation"

Solution:

• Verify marked.js loaded (check browser console)
• Ensure markdown syntax is correct
• Try basic markdown first (bold, italic)
• Check browser supports ES6+ JavaScript

Getting Help

# Main help
markdown-quiz-exporter-tool --help

# Command-specific help
markdown-quiz-exporter-tool flashhero --help
markdown-quiz-exporter-tool anki --help
markdown-quiz-exporter-tool quiz-html --help

# Version information
markdown-quiz-exporter-tool --version

# Shell completion
markdown-quiz-exporter-tool completion bash
markdown-quiz-exporter-tool completion zsh

Exit Codes

• 0: Success
• 1: Error (file not found, parse error, write error, etc.)

Output Formats

Flashcard Hero TSV:

• Tab-separated values
• Two columns: Question, Answer
• Multiple correct answers joined with "; "

Anki AllInOne CSV:

• Semicolon-separated values
• 12 columns with question, answer options, correct answers
• Maximum 5 answer options per question

Anki Basic CSV:

• Semicolon-separated values
• 3 columns: Front, Back, Tags
• Simple question/answer format

HTML Quiz:

• Self-contained HTML5 file
• Embedded JSON quiz data
• Embedded JavaScript application
• Tailwind CSS via CDN
• Marked.js for markdown rendering
• Typically 30-50 KB file size

Best Practices

1. Validate Quiz Format: Always check your markdown follows the format specification before exporting
2. Use Verbosity: Add -vv when debugging to see detailed error messages
3. Keep Backups: Use --force carefully to avoid overwriting important files
4. Test HTML Quiz: Open generated HTML in browser to verify all features work correctly
5. Limit Answer Options: For Anki AllInOne format, keep questions to 5 or fewer options
6. Use Categories: Add category prefixes (e.g., "S3:", "IAM:") for better organization in HTML quiz
7. Write Clear Explanations: Use markdown formatting in explanations for better readability
8. Mobile Testing: Test HTML quiz on mobile devices for responsive design verification

Resources

• GitHub: https://github.com/dnvriend/markdown-quiz-exporter-tool
• Documentation: See README.md in repository
• Quiz Format: See example-quiz.md for format reference
• HTML Example: See example-quiz.html for generated output example