✨ enable upstream updates

README.md

@@ -33,6 +33,7 @@ A Flask-based webcomic website with server-side rendering using Jinja2 templates
   - [Reporting Violations](#reporting-violations)
 - [Project Structure](#project-structure)
 - [Setup](#setup)
+- [Keeping Your Fork Up-to-Date](#keeping-your-fork-up-to-date)
 - [Environment Variables](#environment-variables)
 - [Configuration](#configuration)
   - [Global Settings](#global-settings)
@@ -632,12 +633,14 @@ Resources:
 ```
 sunday/
 ├── app.py                    # Main Flask application
-├── comics_data.py            # Global configuration (not comic data)
+├── comics_data.py            # Global configuration (your settings)
+├── comics_data.py.example    # Configuration template (reference for new options)
 ├── data_loader.py            # YAML comic loader with caching
 ├── requirements.txt          # Python dependencies
 ├── Dockerfile                # Production Docker image
 ├── docker-compose.yml        # Docker Compose configuration
 ├── .dockerignore             # Docker build exclusions
+├── UPSTREAM.md               # Guide for keeping forks up-to-date
 ├── data/                     # Comic data directory
 │   └── comics/              # Individual comic YAML files
 │       ├── 001.yaml         # Comic #1
@@ -663,7 +666,8 @@ sunday/
 │   └── 404.html             # Error page
 └── static/                  # Static files
     ├── css/
-    │   └── style.css        # Main stylesheet
+    │   ├── variables.css    # Design variables (your customization)
+    │   └── style.css        # Core framework styles
     ├── js/
     │   └── comic-nav.js     # Client-side navigation
     ├── images/              # Image directory
@@ -688,6 +692,38 @@ python app.py
 
 3. Visit http://127.0.0.1:3000 in your browser
 
+## Keeping Your Fork Up-to-Date
+
+**If you forked Sunday Comics to create your own webcomic site**, you can stay up-to-date with framework improvements while keeping your customizations.
+
+Sunday Comics is designed with a **fork-and-customize workflow**:
+- ✅ **Core framework files** (app.py, templates, scripts) - updated by upstream
+- ✅ **User customization** (comics_data.py, variables.css) - your settings
+- ✅ **User content** (comics, images, markdown) - your creative work
+
+When you pull upstream updates, you'll get new features and bug fixes without losing your content or design.
+
+**📖 [Read the complete guide: UPSTREAM.md](UPSTREAM.md)**
+
+The UPSTREAM.md guide covers:
+- Setting up your fork with an upstream remote
+- Pulling and merging updates
+- Handling merge conflicts (with examples)
+- Understanding which files to modify vs. leave alone
+- Troubleshooting common issues
+
+**Quick update workflow:**
+```bash
+# Every few weeks/months:
+git fetch upstream                    # Get new commits
+git merge upstream/main               # Merge updates
+# Resolve any conflicts if needed
+git push origin main                  # Push to your fork
+python scripts/publish_comic.py       # Rebuild site
+```
+
+**First time?** See [UPSTREAM.md](UPSTREAM.md) for the initial setup steps.
+
 ## Environment Variables
 
 The app can be configured via environment variables:
@@ -1118,8 +1154,9 @@ For larger comic archives, consider replacing the `COMICS` list with a database:
 - Customize logo by setting `LOGO_IMAGE` and `LOGO_MODE`
 
 ### Styling
-- Modify `static/css/style.css` to change colors, fonts, and layout
-- Current color scheme uses blue (#3498db) and dark blue-gray (#2c3e50)
+- **Customize design:** Edit `static/css/variables.css` to change colors, fonts, spacing, and layout dimensions
+- **Framework styles:** `static/css/style.css` contains core styles that reference the variables (avoid modifying for easier upstream updates)
+- Variables are organized by category: Colors, Typography, Spacing, Borders, Layout, Transitions
 
 ### About Page
 - Edit `content/about.md` to add your bio and comic information (supports markdown)