quizmd 2.1.0

Run markdown quizzes in the terminal

quizmd

quizmd runs markdown-based quizzes in the terminal with timers, single/multiple choice support, and answer export.

Install

Install from PyPI (recommended):

pip install quizmd

Install directly from GitHub (latest repo state):

pip install "git+https://github.com/steliosot/quizmd.git"

For a reproducible install, pin a release tag:

pip install "git+https://github.com/steliosot/quizmd.git@v2.1.0"

Then check the CLI:

quizmd --version

If you already installed it and want the latest updates:

pip install --upgrade --force-reinstall "git+https://github.com/steliosot/quizmd.git"

Add it to requirements.txt if you want teammates/students to install from GitHub:

git+https://github.com/steliosot/quizmd.git

Install vs Examples

• pip install ... installs the quizmd command.
• git clone ... downloads this repository so you can use the bundled example quizzes.

Run a Quiz

If you want the bundled examples, clone the repo:

git clone https://github.com/steliosot/quizmd.git
cd quizmd
quizmd quizzes/harry-potter-quiz.md

Quickest start for new users:

quizmd init
quizmd --validate hello-quiz.md
quizmd hello-quiz.md

Validate quiz files without running the interactive UI:

quizmd --validate quizzes/harry-potter-quiz.md

Validate and run an essay quiz:

quizmd --validate essays/requirements-txt-essay.md
export GEMINI_API_KEY="your_key_here"
quizmd essays/requirements-txt-essay.md

Optional AI settings for essay mode:

quizmd --ai-provider auto --ai-timeout 30 essays/requirements-txt-essay.md
quizmd --ai-provider gemini --ai-model gemini-flash-latest --ai-timeout 30 essays/requirements-txt-essay.md
quizmd --ai-provider openai --ai-model gpt-4o-mini --ai-timeout 30 essays/requirements-txt-essay.md
quizmd --ai-provider anthropic --ai-model claude-3-5-haiku-latest --ai-timeout 30 essays/requirements-txt-essay.md

--ai-timeout must be greater than zero. --ai-provider auto (default) checks keys in this order: GEMINI_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY. If the first provider fails at runtime, auto mode tries the next available provider before falling back to deterministic feedback.

Security notes:

• Never hardcode or commit API keys in source control.
• Use environment variables only:
  • GEMINI_API_KEY
  • OPENAI_API_KEY
  • ANTHROPIC_API_KEY
• If a key is exposed, rotate/revoke it immediately.

Privacy note:

• Essay answers are only saved if you choose y at the save prompt.
• Choose n to keep answers out of local answers/ files.

Theme options for better readability on light or dark terminals:

quizmd --theme auto quizzes/harry-potter-quiz.md
quizmd --theme light quizzes/harry-potter-quiz.md
quizmd --theme dark quizzes/harry-potter-quiz.md

Windows Setup Notes

Create and activate a virtual environment on Windows:

python -m venv .venv
.venv\Scripts\activate

Install and run:

pip install "git+https://github.com/steliosot/quizmd.git"
quizmd --version
quizmd --validate .\quizzes\harry-potter-quiz.md
quizmd .\quizzes\harry-potter-quiz.md

Example Quizzes Included (No LLM Needed)

• quizzes/harry-potter-quiz.md
• quizzes/world-geography-quiz.md
• quizzes/python-basics-quiz.md
• quizzes/math-foundations-quiz.md
• quizzes/history-and-civics-quiz.md
• quizzes/general-science-quiz.md

Essay Examples (LLM-Based)

Essay files are separate and use Gemini evaluation:

• essays/requirements-txt-essay.md
• essays/venv-essay.md
• essays/pinned-versions-essay.md

MCQ quizzes in quizzes/ do not call LLMs and do not need GEMINI_API_KEY.

Simple Quiz Example

Create a file named my-quiz.md:

# My First Quiz

## Question 1
What is 2 + 2?

- 3
- 4
- 5

Answer: 2
Type: single
Time: 20
Explanation: 2 + 2 is 4.

Run it:

quizmd --validate my-quiz.md
quizmd my-quiz.md

Guide: How to Create a Quiz

1. Start with a single # quiz title.
2. Add each question as a ## block.
3. Put the question text on the next line.
4. Add answer options using - bullet lines.
5. Add required fields:
   • Answer: (1-based indexes, comma-separated for multiple)
   • Type: (single or multiple)
6. Add optional fields:
   • Time: positive integer seconds
   • Explanation: any text
7. Run quizmd --validate your-quiz.md before sharing.

Quiz File Rules

• Each question must start with ##.
• Text outside the title and ## blocks is rejected.
• Answer: is required and must be valid indexes.
• Type: is required and must be single or multiple.
• Duplicate answers like Answer: 2,2 are rejected.
• Time: (if present) must be greater than zero.

Common Validation Errors

• missing required field(s): options
• missing required field(s): answer
• missing required field(s): type
• duplicate answer indexes
• unsupported question type
• unexpected content outside question blocks
• no valid questions found

Student End-to-End Check (Clean Environment)

Use these exact steps before class to confirm everything works:

python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install "git+https://github.com/steliosot/quizmd.git"
quizmd --version
git clone https://github.com/steliosot/quizmd.git
cd quizmd
quizmd --validate quizzes/harry-potter-quiz.md
quizmd quizzes/harry-potter-quiz.md

Development

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python -m unittest discover -s tests -q

Releases

• Release tags are immutable.
• Never retag an existing version.
• Publish a new tag for every release (v2.0.3, v2.0.4, ...).
• See CHANGELOG.md and RELEASE.md.
• PyPI publishing is configured via GitHub Trusted Publishing in .github/workflows/release.yml.

Community

• Contributing guide: CONTRIBUTING.md
• Code of Conduct: CODE_OF_CONDUCT.md
• Security policy: SECURITY.md
• License: LICENSE