markdown-quiz-exporter-tool

A CLI tool that exports the quiz-markdown-format to tools like Anki, Flashcard Hero

About
Features
Installation
Usage
Multi-Level Verbosity Logging
Shell Completion
Development
Testing
Security
Contributing
License
Author

About

markdown-quiz-exporter-tool is a Python CLI tool built with modern tooling and best practices.

Features

✅ Validation:
- Detailed error reporting with line numbers
- Context-aware error messages
- Quiz statistics (question types, answer counts)
- Explanation coverage analysis
📤 Export Formats:
- Interactive HTML quiz with dark/light mode
- Flashcard Hero TSV format
- Anki AllInOne (quiz) format
- Anki Basic (recall) format
🎨 HTML Quiz Features:
- Self-contained single HTML file
- Dark/light mode with auto-detect
- Question/answer shuffling
- Progress tracking and timer
- Session storage persistence
- Mobile-responsive design
- Markdown rendering in explanations
✅ Type-safe with mypy strict mode
✅ Linted with ruff
✅ Tested with pytest
📊 Multi-level verbosity logging (-v/-vv/-vvv)
🐚 Shell completion for bash, zsh, and fish
🔒 Security scanning with bandit, pip-audit, and gitleaks
✅ Modern Python tooling (uv, mise, click)

Installation

Prerequisites

Python 3.14 or higher
uv package manager

Install from source

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

# Install globally with uv
uv tool install .

Install with mise (recommended for development)

cd markdown-quiz-exporter-tool
mise trust
mise install
uv sync
uv tool install .

Verify installation

markdown-quiz-exporter-tool --version

Usage

Validate Quiz File

Before exporting, validate your quiz markdown file to check for errors:

# Basic validation
markdown-quiz-exporter-tool validate quiz.md

# With verbose debugging
markdown-quiz-exporter-tool validate quiz.md -vv

On Success, shows statistics:

Total questions (single choice vs multiple choice)
Answer statistics
Explanation coverage

On Error, shows:

Exact line number and problematic content
Context lines (2 before, 2 after)
Clear error message with fix suggestions

The tool provides four main export commands:

1. Interactive HTML Quiz

Generate a self-contained interactive HTML quiz that can be opened in any web browser:

# Basic export
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 "AWS Quiz" --force

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

Features:

Self-contained: Single HTML file with embedded CSS and JavaScript
Dark/Light Mode: Automatic theme detection with manual toggle
Countdown Timer: Optional time limit with pause/resume functionality
Shuffling: Configurable question and answer randomization
Progress Tracking: Visual progress bar
Session Persistence: Saves progress in browser storage (timer resets on refresh)
Mobile Responsive: Works on all screen sizes
Markdown Support: Renders markdown in explanations
Multiple Question Types: Supports both single and multiple choice

Opening the Quiz: Simply open the generated HTML file in any modern web browser. No server or internet connection required after generation.

2. Flashcard Hero Export

Export quiz markdown files to Flashcard Hero TSV format:

# 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
markdown-quiz-exporter-tool flashhero quiz.md flashcards.tsv -vv