diff --git a/README.md b/README.md
new file mode 100644
index 0000000..f57c66a
--- /dev/null
+++ b/README.md
@@ -0,0 +1,199 @@
+# 🗺️ Geoscripting Memes Slideshow
+
+A fun, interactive web-based slideshow featuring programming and geoscripting memes to brighten up your coding sessions! Perfect for coffee breaks, lecture intermissions, or whenever you need a good laugh while working with GIS, Python, R, Bash, and other geoscripting tools.
+
+## 🎯 Features
+
+- **📱 Interactive Slideshow**: Auto-playing meme slideshow with smooth transitions
+- **🎮 Media Controls**: Play/pause, previous/next navigation
+- **⏱️ Customizable Timing**: Adjustable interval from 10 to 120 seconds
+- **📁 Category Selection**: Choose which meme categories to include in your slideshow
+- **📱 Responsive Design**: Works on desktop, tablet, and mobile devices
+- **🔄 Auto-Updates**: GitHub Actions automatically updates the meme database when new memes are added
+
+## 🎭 Meme Categories
+
+The collection includes memes about:
+
+- **🤖 AI** - Artificial Intelligence and machine learning humor
+- **💻 Bash** - Shell scripting and command line jokes
+- **🎉 Friday** - End-of-week celebration memes
+- **📝 General** - General programming and coding humor
+- **🔀 Git** - Version control struggles and victories
+- **⚖️ Licenses** - Open source licensing humor
+- **😴 Monday** - Monday motivation (or lack thereof)
+- **📊 Project&Assignment** - Project management and deadline stress
+- **🐍 Python** - Python programming jokes
+- **📈 R** - R programming and statistics humor
+
+## 🚀 Quick Start
+
+### Option 1: View Online (Recommended)
+If this repository is hosted on GitHub Pages, you can view the slideshow directly at:
+`https://wybrendejong.github.io/geoscripting-memes/`
+
+### Option 2: Run Locally
+
+1. **Clone the repository**:
+   ```bash
+   git clone https://github.com/wybrendejong/geoscripting-memes.git
+   cd geoscripting-memes
+   ```
+
+2. **Serve the files**:
+   
+   Using Python:
+   ```bash
+   python -m http.server 8000
+   ```
+   
+   Using Node.js:
+   ```bash
+   npx serve .
+   ```
+   
+   Or simply open `index.html` in your web browser.
+
+3. **Open in browser**:
+   Navigate to `http://localhost:8000` (or the appropriate URL for your server)
+
+## 🎮 How to Use
+
+1. **🎵 Auto-Play**: The slideshow starts automatically when you load the page
+2. **⏸️ Play/Pause**: Click the play/pause button to control playback
+3. **⏭️ Navigate**: Use the previous/next buttons to manually browse memes
+4. **📁 Select Categories**: Click the folder button to choose which meme categories to include
+5. **⏱️ Adjust Timing**: Use the slider to change how long each meme is displayed (10-120 seconds)
+
+## 🤝 Contributing New Memes
+
+Want to add your favorite geoscripting memes? Here's how:
+
+### Adding Memes
+
+1. **Fork and clone** this repository
+2. **Choose the right category** or create a new one:
+   ```
+   memes/
+   ├── AI/
+   ├── Bash/
+   ├── Friday/
+   ├── General/
+   ├── Git/
+   ├── Your-New-Category/  # Create new folder if needed
+   └── ...
+   ```
+
+3. **Add your meme images**:
+   - Supported formats: `.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`
+   - Keep file sizes reasonable (< 2MB recommended)
+   - Use descriptive filenames
+
+4. **Update the meme database** (optional):
+   ```bash
+   python generate_memes_json.py
+   ```
+   > **Note**: This step is optional as GitHub Actions will automatically update `memes.json` when you push changes.
+
+5. **Submit a pull request** with your new memes!
+
+### Guidelines for Meme Contributions
+
+- ✅ Keep it appropriate and fun
+- ✅ Ensure memes are related to programming, GIS, or geoscripting
+- ✅ Respect copyright - only use memes you have rights to or that are freely available
+- ✅ Check that your memes aren't already in the collection
+
+## 🛠️ Technical Details
+
+### Project Structure
+
+```
+geoscripting-memes/
+├── index.html              # Main slideshow interface
+├── css/
+│   └── styles.css          # Slideshow styling
+├── js/
+│   └── slideshow.js        # Slideshow functionality
+├── memes/                  # Meme image directories
+│   ├── AI/
+│   ├── Bash/
+│   ├── Friday/
+│   └── ...
+├── generate_memes_json.py  # Script to build meme database
+├── memes.json             # Auto-generated meme database
+└── .github/
+    └── workflows/
+        └── update-memes.yml # Auto-update workflow
+```
+
+### Technologies Used
+
+- **Frontend**: Pure HTML5, CSS3, and JavaScript (no frameworks)
+- **Automation**: Python 3 for meme database generation
+- **CI/CD**: GitHub Actions for automatic updates
+- **Hosting**: Ready for GitHub Pages deployment
+
+### The Meme Database
+
+The `memes.json` file is automatically generated by `generate_memes_json.py` and contains:
+
+```json
+{
+  "CategoryName": [
+    "memes/CategoryName/meme1.jpg",
+    "memes/CategoryName/meme2.png",
+    "..."
+  ]
+}
+```
+
+### GitHub Actions Workflow
+
+The repository includes an automated workflow (`.github/workflows/update-memes.yml`) that:
+
+1. **Triggers** when memes are added or the script is modified
+2. **Runs** the meme database generator
+3. **Commits** the updated `memes.json` automatically
+4. **Ensures** the slideshow always reflects the latest meme collection
+
+## 🔧 Development
+
+### Prerequisites
+
+- Python 3.x (for meme database generation)
+- A modern web browser
+- A local web server (optional, for development)
+
+### Making Changes
+
+1. **Clone and set up**:
+   ```bash
+   git clone https://github.com/wybrendejong/geoscripting-memes.git
+   cd geoscripting-memes
+   ```
+
+2. **Make your changes** to HTML, CSS, or JavaScript files
+
+3. **Test locally** by serving the files and opening in a browser
+
+4. **Update memes.json** if you added new memes:
+   ```bash
+   python generate_memes_json.py
+   ```
+
+5. **Submit a pull request** with your improvements!
+
+## 📝 License
+
+This project is open source. Please ensure any memes you contribute comply with copyright laws and fair use guidelines.
+
+## 🎉 Credits
+
+Created for the geoscripting community to add some humor to the coding process. Special thanks to all contributors who help grow this collection of programming memes!
+
+---
+
+**Enjoy the memes and happy coding! 🚀✨**
+
+*If you find this project useful or entertaining, please consider giving it a ⭐ star on GitHub!*
\ No newline at end of file
diff --git a/memes.json b/memes.json
index 035dc6e..23ec7a2 100644
--- a/memes.json
+++ b/memes.json
@@ -1,25 +1,28 @@
 {
-  "AI": [
-    "memes/AI/Meme4.jpg"
-  ],
-  "Bash": [
-    "memes/Bash/bash_204b.jpg",
-    "memes/Bash/bash_41ec.jpg",
-    "memes/Bash/bash_42b9.jpg",
-    "memes/Bash/bash_8565.png",
-    "memes/Bash/bash_a45a.jpg",
-    "memes/Bash/bash_e854.png"
+  "Monday": [
+    "memes/Monday/monday_48e4.jpg",
+    "memes/Monday/monday_4de4.jpg",
+    "memes/Monday/monday_962b.jpg",
+    "memes/Monday/monday_9a97.jpg",
+    "memes/Monday/monday_b852.jpg",
+    "memes/Monday/monday_c493.jpg"
   ],
-  "Friday": [
-    "memes/Friday/friday_4529.jpg",
-    "memes/Friday/friday_4683.png",
-    "memes/Friday/friday_4ee2.jpg",
-    "memes/Friday/friday_560b.jpg",
-    "memes/Friday/friday_8e3a.jpg",
-    "memes/Friday/friday_8ec2.jpg",
-    "memes/Friday/friday_b30b.jpg",
-    "memes/Friday/friday_b381.jpg",
-    "memes/Friday/friday_e8bc.png"
+  "R": [
+    "memes/R/R-vector.jpg",
+    "memes/R/R_3467.jpeg",
+    "memes/R/R_496b.png",
+    "memes/R/R_4a97.jpg",
+    "memes/R/R_4c5c.jpg",
+    "memes/R/R_4e94.png",
+    "memes/R/R_63c5.png",
+    "memes/R/R_7a2d.jpg",
+    "memes/R/R_8e00.png",
+    "memes/R/R_a1bb.png",
+    "memes/R/R_a4ee.jpg",
+    "memes/R/R_a57a.jpeg",
+    "memes/R/R_b036.webp",
+    "memes/R/R_d1d3.png",
+    "memes/R/git_7b71.png"
   ],
   "General": [
     "memes/General/comments.jpg",
@@ -84,6 +87,27 @@
     "memes/General/geoscripting-ta.jpg",
     "memes/General/recursion.jpg"
   ],
+  "Project&Assignment": [
+    "memes/Project&Assignment/assign_d9d2.png",
+    "memes/Project&Assignment/ex5_8447.png",
+    "memes/Project&Assignment/geoscripting_project.jpg",
+    "memes/Project&Assignment/project_1d3a.jpg",
+    "memes/Project&Assignment/project_227a.jpg",
+    "memes/Project&Assignment/project_4677.jpg",
+    "memes/Project&Assignment/project_49fd.png",
+    "memes/Project&Assignment/project_4a92.jpg",
+    "memes/Project&Assignment/project_4d37.jpg",
+    "memes/Project&Assignment/project_873e.jpg",
+    "memes/Project&Assignment/project_9d3d.png",
+    "memes/Project&Assignment/project_b773.png",
+    "memes/Project&Assignment/project_f7ad.jpg"
+  ],
+  "Licenses": [
+    "memes/Licenses/License.jpg",
+    "memes/Licenses/git_35f9.jpg",
+    "memes/Licenses/git_46d1.jpg",
+    "memes/Licenses/license2.jpg"
+  ],
   "Git": [
     "memes/Git/Meme1.jpg",
     "memes/Git/Meme10.png",
@@ -133,34 +157,19 @@
     "memes/Git/reddit.jpg",
     "memes/Git/usetheforce.jpg"
   ],
-  "Licenses": [
-    "memes/Licenses/License.jpg",
-    "memes/Licenses/git_35f9.jpg",
-    "memes/Licenses/git_46d1.jpg",
-    "memes/Licenses/license2.jpg"
-  ],
-  "Monday": [
-    "memes/Monday/monday_48e4.jpg",
-    "memes/Monday/monday_4de4.jpg",
-    "memes/Monday/monday_962b.jpg",
-    "memes/Monday/monday_9a97.jpg",
-    "memes/Monday/monday_b852.jpg",
-    "memes/Monday/monday_c493.jpg"
+  "Friday": [
+    "memes/Friday/friday_4529.jpg",
+    "memes/Friday/friday_4683.png",
+    "memes/Friday/friday_4ee2.jpg",
+    "memes/Friday/friday_560b.jpg",
+    "memes/Friday/friday_8e3a.jpg",
+    "memes/Friday/friday_8ec2.jpg",
+    "memes/Friday/friday_b30b.jpg",
+    "memes/Friday/friday_b381.jpg",
+    "memes/Friday/friday_e8bc.png"
   ],
-  "Project&Assignment": [
-    "memes/Project&Assignment/assign_d9d2.png",
-    "memes/Project&Assignment/ex5_8447.png",
-    "memes/Project&Assignment/geoscripting_project.jpg",
-    "memes/Project&Assignment/project_1d3a.jpg",
-    "memes/Project&Assignment/project_227a.jpg",
-    "memes/Project&Assignment/project_4677.jpg",
-    "memes/Project&Assignment/project_49fd.png",
-    "memes/Project&Assignment/project_4a92.jpg",
-    "memes/Project&Assignment/project_4d37.jpg",
-    "memes/Project&Assignment/project_873e.jpg",
-    "memes/Project&Assignment/project_9d3d.png",
-    "memes/Project&Assignment/project_b773.png",
-    "memes/Project&Assignment/project_f7ad.jpg"
+  "AI": [
+    "memes/AI/Meme4.jpg"
   ],
   "Python": [
     "memes/Python/python_1f1e.jpg",
@@ -179,21 +188,12 @@
     "memes/Python/python_b6ca.jpg",
     "memes/Python/python_f669.jpg"
   ],
-  "R": [
-    "memes/R/R-vector.jpg",
-    "memes/R/R_3467.jpeg",
-    "memes/R/R_496b.png",
-    "memes/R/R_4a97.jpg",
-    "memes/R/R_4c5c.jpg",
-    "memes/R/R_4e94.png",
-    "memes/R/R_63c5.png",
-    "memes/R/R_7a2d.jpg",
-    "memes/R/R_8e00.png",
-    "memes/R/R_a1bb.png",
-    "memes/R/R_a4ee.jpg",
-    "memes/R/R_a57a.jpeg",
-    "memes/R/R_b036.webp",
-    "memes/R/R_d1d3.png",
-    "memes/R/git_7b71.png"
+  "Bash": [
+    "memes/Bash/bash_204b.jpg",
+    "memes/Bash/bash_41ec.jpg",
+    "memes/Bash/bash_42b9.jpg",
+    "memes/Bash/bash_8565.png",
+    "memes/Bash/bash_a45a.jpg",
+    "memes/Bash/bash_e854.png"
   ]
 }
\ No newline at end of file