skill-markdown-quiz-exporter-tool

What this skill does

# 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

```bash
# 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

```bash
# 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

<details>
<summary><strong>📖 Core Commands (Click to expand)</strong></summary>

### flashhero - Export to Flashcard Hero

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

**Usage:**
```bash
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:**
```bash
# 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:**
```bash
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:**
```bash
# 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:**
```bash
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:**
```bash
# 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

</details>

<details>
<summary><strong>📝 Quiz Markdown Format (Click to expand)</strong></summary>

### Format Specification

Quiz markdown files must follow this format:

```markdown
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):

```markdown
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:
```markdown
S3: What is the max size of an S3 object in GB?

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

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

---
```

</details>

<details>
<summary><strong>⚙️  Advanced Features (Click to expand)</strong></summary>

### 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 explana