📚 Study Tools Platform
A free, open-source study tool for students — flashcards, quizzes, games, and more.
Built for GitHub Pages. Powered by a single config file. No coding required to customize.
Are you a teacher? Fork this repo and make it your own — any subject, any grade level.
👉 Teacher Setup Guide — step-by-step instructions, no coding experience needed.
✨ What Students Get
📖 Study
| Activity | Description |
|---|
| Learn Mode | Guided study sessions inspired by Seneca Learning. Short interactive slides with adaptive depth (3 tiers), pre/post assessments, reflection prompts, Wiki Writer bonus challenge, 1.5x points multiplier |
| Textbook | Interactive reading with 3 reading levels (Easier/On Grade/Challenge), collapsible sidebar navigation, vocab highlighting, primary source quotes, Key Idea callouts, Quick Checks, reading progress tracking, a highlighter with a "My highlights" list in the sidebar, and "Keep going" links at the end of each chapter |
| Flashcards | Anki-style spaced repetition with 3D flip animation, confidence rating, "Make Your Own Example", vocab tiers (must-know/encounter/bonus), and "Read in textbook" deep-links |
| Short Answer | Visual card-based question selector with topic images, color-coded categories, and key term chips |
| Source Analysis | Primary source analysis using the SIFT method with scoring |
| Typing Practice | Monkeytype-inspired typing with full passages and per-term snippets; works with phone keyboards |
| Resource Library | Searchable vocabulary reference with mastery indicators, Simple Wikipedia and Wikipedia links, and teacher-curated "Go deeper" links (videos, challenge readings, reference articles) per category |
| How to Study | Interactive study strategies page with comprehension quiz and Study Smart badge |
📝 Practice
| Activity | Description |
|---|
| Practice Test | 10-question mastery loop — tracks progress across sessions until every question answered correctly; wrong answers feed back to flashcards |
| Fill-in-the-Blank | One-at-a-time stepper with word bank or type-it mode |
| Timeline | Drag events into chronological order with shuffle, remove, and challenge mode |
🎮 Games
| Activity | Description |
|---|
| Sort It Out | Sort terms into category buckets with streak bonuses and speed timer (1.25x analysis tier) |
| Who Am I? | Guess the term from progressive clues — fewer clues = more points (1.25x analysis tier). Challenge mode: type the answer, every unit term in play, 1.5x points |
| Four Corners | Find the odd one out — 3 terms share a category, 1 does not belong (1.25x analysis tier) |
| Map Quiz | Click-on-the-map geography quiz with 3-strike hint system. Includes 1861 States & Territories map with Learn/Quiz modes and Union/Confederate/Border/Territory color-coding |
| Lightning Round | 60-second speed quiz with leaderboard |
| Crossword | Auto-generated crossword from vocabulary |
| Quiz Race | Timed 1v1 same-screen quiz race with leaderboard |
| Wordle | Guess the vocabulary term in 6 tries with definition clues |
| Tower Defense | 3D tower defense — answer vocab to earn coins, build towers, survive 10 waves |
| Flip Match | Memory matching — pair terms to definitions |
| Hangman | Classic word guessing with definitions |
| Term Catcher | Catch the falling correct term |
🧠 Smart Learning
- Cross-activity weakness tracking — wrong answers feed a shared tracker that surfaces weak terms across Flashcards, Practice Test, Fill-in-the-Blank, Lightning Round, and Typing Practice
- Auto study time tracking — time in activities counts automatically; pauses on inactivity or hidden tab
- Mastery gating — Read > Study > Practice > Play flow: students read the textbook chapter before flashcards unlock, then master terms to unlock games. Vocabulary tiers (must-know/encounter/bonus) focus study on tested terms
- Scheduled unlocks — Optional per-unit
categorySchedule opens categories on a calendar (e.g. one per week) so students who fall behind never get fully shut out. Mastery still accelerates ahead of the schedule
- Achievement system — unlockable badges with confetti for milestones
- Guest mode — parents and visitors can browse without entering a name
🏗️ Platform Features
For Students
- Dark/light theme with Outfit font
- Settings gear with theme toggle, dyslexic font, and search
- Command palette (
/ or Cmd+K)
- OpenDyslexic font toggle
- Study timer, notes, printable guide
- Music player with auto-shuffle, loop, playlist
- Deep linking to activities (
#activity-name)
- Progress tracking (local + optional cloud sync)
- Personalized welcome screen and progress stats
- Quiz date with a days-left countdown on the unit home screen
For Teachers
- Config-driven — one JSON file powers everything
- Optional quiz date countdown (
quizDate in the unit config)
- Hidden teacher dashboard (via command palette)
- Student progress table with edit/delete
- Leaderboard with teacher approval
- Class-vs-class competition view
- Analytics: activity popularity, weak topics
- Question Exporter — turn a unit's practice questions into Blooket or GiMKit CSVs
- Privacy-first — see privacy policy
📁 Project Structure
study-tools/
├── engine/ # The app (don't need to edit)
│ ├── css/styles.css # Theming via CSS custom properties
│ ├── js/core/ # App shell, progress, mastery, leaderboard
│ ├── js/activities/ # One file per activity (plugin system)
│ ├── tools/ # Study tools (notes, timer, music, export) + unit-content-check.js
│ ├── vendor/ # Self-hosted fonts, icons, Supabase SDK
│ └── index.html # Main app shell
├── units/ # Your content goes here
│ ├── units.json # Unit manifest
│ └── early-republic/ # Example unit (complete reference)
│ ├── config.json # Vocabulary, questions, timeline, theme, Go Deeper links
│ └── textbook.json # Leveled textbook chapters, one per vocabulary category
├── dashboard/ # Teacher dashboard (standalone)
└── database/ # Supabase schema + migrations
To customize content, you only edit files in units/. The engine reads your config.json and builds everything automatically.
🚀 Quick Start
For teachers (no coding)
- Fork this repo
- Run
./setup.sh to remove the example content and start fresh
- Add your own vocabulary and questions to a
config.json file
- Enable GitHub Pages — your site is live
See the Teacher Guide for the full walkthrough.
For developers
# Clone the repo
git clone https://github.com/shiebenaderet/studytools.git
# Serve locally (any static server works)
cd studytools
python3 -m http.server 8000
# Open in browser
open http://localhost:8000/study-tools/engine/?unit=early-republic
No build step. No dependencies to install. Just HTML, CSS, and JavaScript.
Before a unit goes live, check it:
node study-tools/engine/tools/unit-content-check.js <unit-id>
Conventions for building units and changing the engine (phone keyboards, Go Deeper links, sync, testing) are in CLAUDE.md, which Claude Code also reads at the start of every session.
🔧 Tech Stack
Privacy: All fonts, icons, and scripts are self-hosted. No third-party analytics, no cookies, no tracking. See the privacy page.
🔒 Privacy & Security
- No student emails, passwords, or accounts
- No cookies, tracking, or third-party analytics
- All assets self-hosted (no CDN IP leakage)
- Guest mode for anonymous browsing
- Supabase RLS policies restrict data access
- COPPA school exception documented
- Teacher approval required for leaderboard visibility
- Full privacy policy
🙌 Student Contributors
Students who reported bugs or suggested improvements:
| Student | Contribution |
|---|
| Ahmad | Found the leaderboard scoring bug where map quiz scores above 100% weren't being counted |
| Fabian | Reported Wordle display issue with abbreviated terms |
| Tianyu | Reported that misclicking blank space on map quizzes was incorrectly marked wrong |
| Tianyu | Reported that spam-clicking the answer on map quizzes skipped questions and marked them automatically |
| Braden | Reported that games and other activities stayed locked even after the scheduled unlock dates had passed |
| Tianyu | Lost his first-place progress after clearing his browser, which revealed a bug where logging in on a fresh device could overwrite a saved leaderboard score |
| Brandon K | Reported that Fill in the Blank's Next button stayed stuck after typing an answer, and that the answer box had no length limit |
| Kyler | Suggested playing Hangman without the clue and revealing it afterward — now Hangman's Hard Mode |
| Maddy W | Pointed out the long pause after each correct colony on the 13 Colonies quiz and that correct colonies should stay colored, GeoGuessr-style — now Maddy's Madness Mode and sticky green colonies |
| Tiffany | Asked for GimKit-style games; the question exporter now confirms GimKit downloads on the page |
| Anderson A | Reported that Typing Practice let you type any word on a phone, which revealed that Android keyboards never sent the space bar to the site |
| Tiffany N | Asked for a harder Who Am I, which revealed that most clues contained the answer; now masked, plus a typed-answer Challenge mode |
| Tiffany N | Asked for a textbook highlighter, now with a "My highlights" list |
| Anderson A | Asked for more reading and study options after outgrowing the games; now Go deeper links in every chapter |
Want to be listed here? Report a bug or suggest an improvement to your teacher!
📄 License
For educational use.
