Initial commit
This commit is contained in:
Zhongwei Li
14
.claude-plugin/plugin.json
Normal file
14
.claude-plugin/plugin.json
Normal file
@@ -0,0 +1,14 @@
|
||||
{
|
||||
"name": "markdown-quiz-exporter-tool",
|
||||
"description": "CLI tool for exporting quiz markdown to multiple formats",
|
||||
"version": "0.1.0",
|
||||
"author": {
|
||||
"name": "Dennis Vriend"
|
||||
},
|
||||
"skills": [
|
||||
"./skills"
|
||||
],
|
||||
"commands": [
|
||||
"./commands"
|
||||
]
|
||||
}
|
||||
3
README.md
Normal file
3
README.md
Normal file
@@ -0,0 +1,3 @@
|
||||
# markdown-quiz-exporter-tool
|
||||
|
||||
CLI tool for exporting quiz markdown to multiple formats
|
||||
38
commands/anki.md
Normal file
38
commands/anki.md
Normal file
@@ -0,0 +1,38 @@
|
||||
---
|
||||
description: Export quiz to Anki CSV format
|
||||
argument-hint: input.md output.csv
|
||||
---
|
||||
|
||||
Export quiz markdown to Anki CSV format (AllInOne or Basic).
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
markdown-quiz-exporter-tool anki INPUT.md OUTPUT.csv [OPTIONS]
|
||||
```
|
||||
|
||||
## Arguments
|
||||
|
||||
- `INPUT.md`: Quiz markdown file (required)
|
||||
- `OUTPUT.csv`: Output CSV file (required)
|
||||
- `--quiz`: AllInOne quiz format (default)
|
||||
- `--recall`: Basic recall format
|
||||
- `--force` / `-f`: Overwrite existing file
|
||||
- `-v/-vv/-vvv`: Verbosity (INFO/DEBUG/TRACE)
|
||||
|
||||
## Examples
|
||||
|
||||
```bash
|
||||
# Export as quiz (default)
|
||||
markdown-quiz-exporter-tool anki quiz.md cards.csv
|
||||
|
||||
# Export as recall
|
||||
markdown-quiz-exporter-tool anki quiz.md cards.csv --recall
|
||||
|
||||
# Overwrite existing
|
||||
markdown-quiz-exporter-tool anki quiz.md cards.csv --force
|
||||
```
|
||||
|
||||
## Output
|
||||
|
||||
CSV with AllInOne (quiz) or Basic (recall) format.
|
||||
36
commands/flashhero.md
Normal file
36
commands/flashhero.md
Normal file
@@ -0,0 +1,36 @@
|
||||
---
|
||||
description: Export quiz to Flashcard Hero TSV format
|
||||
argument-hint: input.md output.tsv
|
||||
---
|
||||
|
||||
Export quiz markdown to Flashcard Hero TSV format.
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
markdown-quiz-exporter-tool flashhero INPUT.md OUTPUT.tsv [OPTIONS]
|
||||
```
|
||||
|
||||
## Arguments
|
||||
|
||||
- `INPUT.md`: Quiz markdown file (required)
|
||||
- `OUTPUT.tsv`: Output TSV file (required)
|
||||
- `--force` / `-f`: Overwrite existing file
|
||||
- `-v/-vv/-vvv`: Verbosity (INFO/DEBUG/TRACE)
|
||||
|
||||
## Examples
|
||||
|
||||
```bash
|
||||
# Basic export
|
||||
markdown-quiz-exporter-tool flashhero quiz.md flashcards.tsv
|
||||
|
||||
# Overwrite existing
|
||||
markdown-quiz-exporter-tool flashhero quiz.md flashcards.tsv --force
|
||||
|
||||
# With verbose output
|
||||
markdown-quiz-exporter-tool flashhero quiz.md flashcards.tsv -vv
|
||||
```
|
||||
|
||||
## Output
|
||||
|
||||
TSV file with: Question<TAB>Answer format.
|
||||
44
commands/help.md
Normal file
44
commands/help.md
Normal file
@@ -0,0 +1,44 @@
|
||||
---
|
||||
description: Show help information for markdown-quiz-exporter-tool
|
||||
argument-hint: command
|
||||
---
|
||||
|
||||
Display help information for markdown-quiz-exporter-tool CLI commands.
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
# Show general help
|
||||
markdown-quiz-exporter-tool --help
|
||||
|
||||
# Show command-specific help
|
||||
markdown-quiz-exporter-tool COMMAND --help
|
||||
|
||||
# Show version
|
||||
markdown-quiz-exporter-tool --version
|
||||
```
|
||||
|
||||
## Arguments
|
||||
|
||||
- `COMMAND` (optional): Specific command to get help for
|
||||
- `--help` / `-h`: Show help information
|
||||
- `--version` / `-v`: Show version information
|
||||
|
||||
## Examples
|
||||
|
||||
```bash
|
||||
# General help
|
||||
markdown-quiz-exporter-tool --help
|
||||
|
||||
# Command help
|
||||
markdown-quiz-exporter-tool quiz-html --help
|
||||
markdown-quiz-exporter-tool flashhero --help
|
||||
markdown-quiz-exporter-tool anki --help
|
||||
|
||||
# Version information
|
||||
markdown-quiz-exporter-tool --version
|
||||
```
|
||||
|
||||
## Output
|
||||
|
||||
Displays usage information, available commands, and options.
|
||||
37
commands/quiz-html.md
Normal file
37
commands/quiz-html.md
Normal file
@@ -0,0 +1,37 @@
|
||||
---
|
||||
description: Generate interactive HTML quiz from markdown
|
||||
argument-hint: input.md output.html
|
||||
---
|
||||
|
||||
Generate self-contained interactive HTML quiz page.
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
markdown-quiz-exporter-tool quiz-html INPUT.md OUTPUT.html --title "TITLE" [OPTIONS]
|
||||
```
|
||||
|
||||
## Arguments
|
||||
|
||||
- `INPUT.md`: Quiz markdown file (required)
|
||||
- `OUTPUT.html`: Output HTML file (required)
|
||||
- `--title "TITLE"`: Quiz title (required)
|
||||
- `--force` / `-f`: Overwrite existing file
|
||||
- `-v/-vv/-vvv`: Verbosity (INFO/DEBUG/TRACE)
|
||||
|
||||
## Examples
|
||||
|
||||
```bash
|
||||
# Generate quiz HTML
|
||||
markdown-quiz-exporter-tool quiz-html quiz.md quiz.html --title "My Quiz"
|
||||
|
||||
# Overwrite existing
|
||||
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
|
||||
```
|
||||
|
||||
## Output
|
||||
|
||||
Self-contained HTML with embedded quiz, CSS, and JavaScript.
|
||||
72
commands/validate.md
Normal file
72
commands/validate.md
Normal file
@@ -0,0 +1,72 @@
|
||||
---
|
||||
description: Validate quiz markdown file format
|
||||
argument-hint: input.md
|
||||
---
|
||||
|
||||
Validate quiz markdown file format and show statistics.
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
markdown-quiz-exporter-tool validate INPUT.md [OPTIONS]
|
||||
```
|
||||
|
||||
## Arguments
|
||||
|
||||
- `INPUT.md`: Quiz markdown file to validate (required)
|
||||
- `-v/-vv/-vvv`: Verbosity (INFO/DEBUG/TRACE)
|
||||
|
||||
## Examples
|
||||
|
||||
```bash
|
||||
# Basic validation
|
||||
markdown-quiz-exporter-tool validate quiz.md
|
||||
|
||||
# With verbose output for debugging
|
||||
markdown-quiz-exporter-tool validate quiz.md -vv
|
||||
```
|
||||
|
||||
## Output
|
||||
|
||||
### On Success
|
||||
|
||||
Shows statistics about the quiz:
|
||||
- Total question count
|
||||
- Single choice vs multiple choice breakdown
|
||||
- Answer statistics (total, average per question, correct count)
|
||||
- Explanation coverage
|
||||
|
||||
### On Error
|
||||
|
||||
Shows detailed error information:
|
||||
- Exact line number where error occurred
|
||||
- Problematic line content
|
||||
- Context lines (2 before, 2 after)
|
||||
- Clear error message with fix suggestions
|
||||
- Question block number
|
||||
|
||||
## Common Errors
|
||||
|
||||
**Mixed answer types:**
|
||||
```
|
||||
Error at line 5: Cannot mix ( ) and [ ] formats in same question
|
||||
```
|
||||
Fix: Use consistent format - either `( )` for single choice OR `[ ]` for multiple choice
|
||||
|
||||
**No correct answer:**
|
||||
```
|
||||
Error at line 3: No correct answer marked. Use (X) or [X]
|
||||
```
|
||||
Fix: Mark at least one answer with `(X)` or `[X]`
|
||||
|
||||
**No answers found:**
|
||||
```
|
||||
Error at line 2: No answers found. Expected format: '- (X) text'
|
||||
```
|
||||
Fix: Add answer options in format `- (X) answer` or `- [X] answer`
|
||||
|
||||
**No question text:**
|
||||
```
|
||||
Error at line 1: No question text found
|
||||
```
|
||||
Fix: Add question text before answer options
|
||||
65
plugin.lock.json
Normal file
65
plugin.lock.json
Normal file
@@ -0,0 +1,65 @@
|
||||
{
|
||||
"$schema": "internal://schemas/plugin.lock.v1.json",
|
||||
"pluginId": "gh:dnvriend/markdown-quiz-exporter-tool:plugins/markdown-quiz-exporter-tool",
|
||||
"normalized": {
|
||||
"repo": null,
|
||||
"ref": "refs/tags/v20251128.0",
|
||||
"commit": "eb766386a6de6589e0d3a011f4682881b81ebc53",
|
||||
"treeHash": "3b18f7255c43a119de4165855b5bccca59e3671d72686df6bc7aeca5a08fb3cb",
|
||||
"generatedAt": "2025-11-28T10:16:36.493150Z",
|
||||
"toolVersion": "publish_plugins.py@0.2.0"
|
||||
},
|
||||
"origin": {
|
||||
"remote": "git@github.com:zhongweili/42plugin-data.git",
|
||||
"branch": "master",
|
||||
"commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
|
||||
"repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
|
||||
},
|
||||
"manifest": {
|
||||
"name": "markdown-quiz-exporter-tool",
|
||||
"description": "CLI tool for exporting quiz markdown to multiple formats",
|
||||
"version": "0.1.0"
|
||||
},
|
||||
"content": {
|
||||
"files": [
|
||||
{
|
||||
"path": "README.md",
|
||||
"sha256": "2359346d1b8f22b732164625534a4f83f6cacebbd2f82bfd6c48281aa4fd34c5"
|
||||
},
|
||||
{
|
||||
"path": ".claude-plugin/plugin.json",
|
||||
"sha256": "6b04516b8d99896a75c9f76e3aa39bf40f4345a76755241599e4758a49ad97ea"
|
||||
},
|
||||
{
|
||||
"path": "commands/quiz-html.md",
|
||||
"sha256": "e533da51ef87fb2178bdd484e76aa6e8e2506fa0368d060160e5c8a5fef07933"
|
||||
},
|
||||
{
|
||||
"path": "commands/validate.md",
|
||||
"sha256": "0f52cd2a7bc0ac902d85dd8e5f72aea14167a0ce3c3d12f8bb9feaf8d6fca888"
|
||||
},
|
||||
{
|
||||
"path": "commands/help.md",
|
||||
"sha256": "702e818536eb4db6ac2bb1ba46f17a87d06f9cefe912b210ef07605193b9ac50"
|
||||
},
|
||||
{
|
||||
"path": "commands/flashhero.md",
|
||||
"sha256": "4753af5d2bf65af1e4b160397526c843fb7b4e210740950ae3971301ddc129dd"
|
||||
},
|
||||
{
|
||||
"path": "commands/anki.md",
|
||||
"sha256": "5ed6cb61fffdbfebb1a4ead5df2fa2b68387ab69b76bda4a7311eb3b3c468dfd"
|
||||
},
|
||||
{
|
||||
"path": "skills/markdown-quiz-exporter-tool/SKILL.md",
|
||||
"sha256": "7e1565699e5a684f8fde1a10e6edcdc57e67adac788e0c654fc5fc1a4af6bee1"
|
||||
}
|
||||
],
|
||||
"dirSha256": "3b18f7255c43a119de4165855b5bccca59e3671d72686df6bc7aeca5a08fb3cb"
|
||||
},
|
||||
"security": {
|
||||
"scannedAt": null,
|
||||
"scannerVersion": null,
|
||||
"flags": []
|
||||
}
|
||||
}
|
||||
509
skills/markdown-quiz-exporter-tool/SKILL.md
Normal file
509
skills/markdown-quiz-exporter-tool/SKILL.md
Normal file
@@ -0,0 +1,509 @@
|
||||
---
|
||||
name: skill-markdown-quiz-exporter-tool
|
||||
description: 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
|
||||
|
||||
```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 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:
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
# 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
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>🔧 Troubleshooting (Click to expand)</strong></summary>
|
||||
|
||||
### Common Issues
|
||||
|
||||
**Issue: "Error: Quiz file not found"**
|
||||
```bash
|
||||
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"**
|
||||
```bash
|
||||
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"**
|
||||
```bash
|
||||
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"**
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
## 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
|
||||
Reference in New Issue
Block a user