markdown-quiz-exporter-tool
A CLI tool that exports the quiz-markdown-format to tools like Anki, Flashcard Hero
Table of Contents
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