214 lines
5.9 KiB
Markdown
214 lines
5.9 KiB
Markdown
# 🐒 Greasemonkey - START HERE
|
|
|
|
**Welcome to Greasemonkey!** This browser extension lets you execute custom JavaScript and CSS on any webpage.
|
|
|
|
---
|
|
|
|
## 🚀 Quick Start (Choose Your Path)
|
|
|
|
### Path 1: I Want To Use It NOW (5 minutes)
|
|
→ **Read [QUICKSTART.md](QUICKSTART.md)** - Get up and running immediately
|
|
|
|
### Path 2: I Want Example Rules
|
|
→ **Read [EXAMPLES.md](EXAMPLES.md)** - 20+ ready-to-use rules to copy/paste
|
|
|
|
### Path 3: I Want Complete Documentation
|
|
→ **Read [README.md](README.md)** - Full feature documentation and usage guide
|
|
|
|
### Path 4: I Want To Test It First
|
|
→ **Open [test-page.html](test-page.html)** in your browser - Interactive test environment
|
|
|
|
### Path 5: I Want To Distribute It
|
|
→ **Read [BUILD.md](BUILD.md)** - Building and distribution instructions
|
|
|
|
---
|
|
|
|
## 📦 Installation (Pick Your Browser)
|
|
|
|
### Google Chrome / Microsoft Edge
|
|
```
|
|
1. Open chrome://extensions/
|
|
2. Enable "Developer mode" (top-right toggle)
|
|
3. Click "Load unpacked"
|
|
4. Select the chrome/ folder
|
|
```
|
|
|
|
### Mozilla Firefox
|
|
```
|
|
1. Open about:debugging#/runtime/this-firefox
|
|
2. Click "Load Temporary Add-on"
|
|
3. Select firefox/manifest.json
|
|
```
|
|
|
|
**That's it!** The Greasemonkey icon appears in your toolbar.
|
|
|
|
---
|
|
|
|
## 📚 Documentation Map
|
|
|
|
| File | What It Contains | When To Read |
|
|
|------|------------------|--------------|
|
|
| **QUICKSTART.md** | 5-minute tutorial | First time setup |
|
|
| **EXAMPLES.md** | 20+ example rules | When you need ideas |
|
|
| **README.md** | Complete documentation | Learning all features |
|
|
| **BUILD.md** | Build instructions | Distributing the extension |
|
|
| **test-page.html** | Test environment | Testing your rules |
|
|
| **PROJECT_SUMMARY.md** | Project overview | Understanding the codebase |
|
|
|
|
---
|
|
|
|
## 🎯 What Can I Do With This?
|
|
|
|
### Popular Use Cases
|
|
- 🌙 **Add Dark Mode** to any website
|
|
- 🚫 **Block Ads** and unwanted content
|
|
- ⚡ **Automate Tasks** like form filling
|
|
- 🎨 **Customize Design** of your favorite sites
|
|
- 🔧 **Add Features** that websites are missing
|
|
- 🔐 **Enhance Privacy** by removing trackers
|
|
- ♿ **Improve Accessibility** with custom styles
|
|
- 📝 **Inject Tools** like notepads or calculators
|
|
|
|
### Example: Make Any Site Dark
|
|
1. Click Greasemonkey icon
|
|
2. Add rule: URL contains `example.com`
|
|
3. Add CSS: `body { background: #1a1a1a !important; color: #e0e0e0 !important; }`
|
|
4. Visit example.com → Dark theme!
|
|
|
|
---
|
|
|
|
## 🎓 Learning Path
|
|
|
|
**Total Time: ~30 minutes**
|
|
|
|
1. **Install** (5 min) → Follow installation steps above
|
|
2. **Quick Start** (5 min) → Read QUICKSTART.md
|
|
3. **First Rule** (5 min) → Create your first rule
|
|
4. **Test** (5 min) → Open test-page.html and experiment
|
|
5. **Examples** (10 min) → Browse EXAMPLES.md for ideas
|
|
6. **Customize** (∞) → Start customizing your favorite sites!
|
|
|
|
---
|
|
|
|
## 📋 Features Checklist
|
|
|
|
✅ URL pattern matching
|
|
✅ CSS selector matching
|
|
✅ Combined URL + element matching
|
|
✅ JavaScript execution
|
|
✅ CSS injection
|
|
✅ Bootstrap dark theme UI
|
|
✅ Add/edit/delete rules
|
|
✅ Enable/disable toggles
|
|
✅ Persistent storage
|
|
✅ Chrome support (Manifest V3)
|
|
✅ Firefox support (Manifest V2)
|
|
✅ Complete documentation
|
|
✅ Example library
|
|
✅ Test page
|
|
|
|
---
|
|
|
|
## 🔧 Technical Details
|
|
|
|
**Architecture:**
|
|
- Content scripts inject at page load
|
|
- Bootstrap 5 dark theme UI
|
|
- Sync storage for persistence
|
|
- No external dependencies
|
|
|
|
**Browser Support:**
|
|
- Chrome 88+ (Manifest V3)
|
|
- Firefox 48+ (Manifest V2)
|
|
- Edge, Opera (Chromium-based)
|
|
|
|
**File Count:**
|
|
- 9 files per browser
|
|
- 7 documentation files
|
|
- 1 test page
|
|
- Total: 26 files
|
|
|
|
---
|
|
|
|
## 🆘 Common Questions
|
|
|
|
**Q: Is it safe?**
|
|
A: Yes! No external servers, no tracking. All code runs locally. Be cautious with JavaScript you execute.
|
|
|
|
**Q: Will it slow down my browser?**
|
|
A: No. Scripts only run when conditions match, and inject efficiently at page load.
|
|
|
|
**Q: Can I share my rules?**
|
|
A: Yes! Copy the rule configuration and share. Rules are just text in your browser storage.
|
|
|
|
**Q: Do I need programming knowledge?**
|
|
A: Basic knowledge helps, but you can start with examples from EXAMPLES.md and modify them.
|
|
|
|
**Q: Can I break websites?**
|
|
A: Unlikely to cause permanent issues. Just disable the rule if something goes wrong. Refresh to reset.
|
|
|
|
**Q: Does it work on all websites?**
|
|
A: Yes, except some with strict Content Security Policy. Works on 99% of sites.
|
|
|
|
---
|
|
|
|
## 🐛 Troubleshooting
|
|
|
|
**Rule not working?**
|
|
1. Check rule is enabled (toggle switch)
|
|
2. Verify URL pattern matches current page
|
|
3. Test element selector in console: `document.querySelector('selector')`
|
|
4. Check browser console (F12) for errors
|
|
5. Reload the page after creating/editing rules
|
|
|
|
**More help:** See troubleshooting section in [README.md](README.md)
|
|
|
|
---
|
|
|
|
## 📞 Support
|
|
|
|
- **Questions?** Check README.md troubleshooting section
|
|
- **Bugs?** Check browser console for errors
|
|
- **Ideas?** Browse EXAMPLES.md for inspiration
|
|
- **Contact:** Andy Dixon (extension author)
|
|
|
|
---
|
|
|
|
## 🎉 Ready To Start!
|
|
|
|
**Recommended first steps:**
|
|
|
|
1. ✅ Install extension in your browser (see above)
|
|
2. ✅ Read [QUICKSTART.md](QUICKSTART.md) (5 minutes)
|
|
3. ✅ Open [test-page.html](test-page.html) in browser
|
|
4. ✅ Create your first rule
|
|
5. ✅ Browse [EXAMPLES.md](EXAMPLES.md) for more ideas
|
|
|
|
---
|
|
|
|
## 📁 File Reference
|
|
|
|
```
|
|
greasemonkey/
|
|
├── START_HERE.md ← You are here!
|
|
├── QUICKSTART.md ← Start here for installation
|
|
├── EXAMPLES.md ← 20+ ready-to-use rules
|
|
├── README.md ← Complete documentation
|
|
├── BUILD.md ← Distribution guide
|
|
├── test-page.html ← Test environment
|
|
├── chrome/ ← Chrome extension files
|
|
└── firefox/ ← Firefox extension files
|
|
```
|
|
|
|
---
|
|
|
|
**Author:** Andy Dixon
|
|
**Version:** 1.0.0
|
|
**License:** Personal and educational use
|
|
|
|
---
|
|
|
|
### 🚀 Let's Go!
|
|
|
|
Pick your path above and start customizing the web! 🐒✨
|