# NewsSync Installation & Setup Guide

## 🎯 Welcome!

This guide will help you install and configure NewsSync (FREE version) on your WordPress site. Whether you're a beginner or experienced developer, we've got you covered.

**What you'll learn:**
- ✅ Basic plugin installation
- ✅ First feed setup (5 minutes)
- ✅ Optional performance optimization (for large sites)
- ✅ Troubleshooting common issues

---

## 📦 Installation (3 Methods)

### Method 1: WordPress Admin (Easiest) ⭐

**Step-by-step:**
1. Go to **WordPress Admin → Plugins → Add New**
2. Search for **"RSS NewsSync"**
3. Click **"Install Now"** → **"Activate"**
4. ✅ Done! Plugin is ready to use

---

### Method 2: Upload ZIP File

**When to use:** Downloaded plugin from WordPress.org or received custom version.

**Step-by-step:**
1. Download plugin ZIP file from [WordPress.org](https://wordpress.org/plugins/rss-newssync/)
2. Go to **WordPress Admin → Plugins → Add New → Upload Plugin**
3. Click **"Choose File"** → Select ZIP
4. Click **"Install Now"** → **"Activate"**
5. ✅ Done!

---

### Method 3: FTP/SFTP (Manual)

**When to use:** Prefer manual installation, troubleshooting install issues.

**Step-by-step:**
1. Download and extract plugin ZIP
2. Connect to your site via FTP/SFTP
3. Upload `rss-newssync` folder to `/wp-content/plugins/`
4. Go to **WordPress Admin → Plugins**
5. Find "RSS NewsSync" and click **"Activate"**
6. ✅ Done!

---

## 🚀 Quick Start: Your First Feed (5 minutes)

### Step 1: Add a shortcode to any page/post

**Easy method (Gutenberg block editor):**
1. Create or edit a page/post
2. Add a **Shortcode block**
3. Paste this example:
   ```
   [newssync feed_url="https://techcrunch.com/feed/"]
   ```
4. Click **"Publish"** or **"Update"**
5. View the page → You should see TechCrunch articles! ✅

**Alternative feeds to try:**
- **BBC News:** `https://feeds.bbci.co.uk/news/rss.xml`
- **The Verge:** `https://www.theverge.com/rss/index.xml`
- **WordPress News:** `https://wordpress.org/news/feed/`

---

### Step 2: Customize your feed display

**Basic customization options:**

```
[newssync
  feed_url="https://techcrunch.com/feed/"
  posts_per_page="5"
  show_excerpt="yes"
  show_date="yes"
  layout="grid"
]
```

**What each option does:**
- `posts_per_page="5"` — Show 5 items (default: 10)
- `show_excerpt="yes"` — Display article excerpt
- `show_date="yes"` — Show publication date
- `layout="grid"` — Grid layout (options: grid, list, minimal)

**📖 Full shortcode reference:** See [Shortcode Documentation](https://daazlabs.com/newssync/docs/shortcodes/)

---

## ⚙️ Settings & Configuration

### Global Settings

Go to **WordPress Admin → Settings → NewsSync** to configure:

**Display Options:**
- **Default layout** — Grid, List, or Minimal
- **Excerpt length** — Number of words (default: 150)
- **Date format** — How dates are displayed
- **Cache duration** — How long feeds are cached (default: 1 hour)

**Content Options:**
- **Open links in new tab** — Yes/No
- **Show featured images** — Yes/No
- **Default thumbnail** — Fallback image for items without images

**Advanced Options:**
- **Debug mode** — Enable detailed logging (for troubleshooting)
- **Force refresh** — Clear all feed caches

---

## 🔧 Performance Optimization (Optional)

### 🤔 Do I Need This?

The plugin works great **out of the box** for most sites. Consider optimization if:

- ✅ You import **100+ feed items per day**
- ✅ Your site has **high traffic** (10,000+ visits/day)
- ✅ You notice **slow page loads** when displaying feeds
- ✅ You have **multiple feeds** (5+ different sources)

**If you're just starting:** 👉 **Skip this section!** Come back later if needed.

---

### ⚡ Performance: Indexed Database Table

By default, NewsSync uses WordPress `postmeta` to track imported items. For large sites, an **indexed database table** is much faster.

**Benefits:**
- 🚀 **10-100x faster** duplicate detection (large datasets)
- 🚀 **Reduced memory usage** (less overhead)
- 🚀 **Better scalability** (handles 10,000+ items easily)

**When it matters:**
| Site Size | Postmeta (default) | Indexed Table |
|-----------|-------------------|---------------|
| **< 100 items** | ✅ Fast (< 0.1s) | ✅ Fast (< 0.01s) — Overkill |
| **100-1000 items** | ⚠️ OK (0.5-1s) | ✅ Fast (< 0.1s) — Recommended |
| **1000+ items** | ❌ Slow (2-5s) | ✅ Fast (< 0.2s) — **Essential** |

---

### 🛠️ Creating the Database Table

#### Option A: Automatic (Plugin Admin) ⭐ **Recommended**

**Coming in v1.1:** Auto-create button in Settings.

**Current workaround:** Use Option B or C below.

---

#### Option B: WP-CLI (Developers/SSH Access)

**Requirements:**
- SSH access to your server
- WP-CLI installed ([Installation guide](https://wp-cli.org/))

**Commands:**

```bash
# Navigate to your WordPress root
cd /var/www/html/your-site

# Activate plugin (if not already)
wp plugin activate rss-newssync

# Create the database table
wp eval 'newssync_create_item_map_table();'

# Verify table exists (replace wp_ with your prefix)
wp db query "SHOW TABLES LIKE 'wp_newssync_item_map';"
```

**Expected output:**
```
+--------------------------------+
| Tables_in_database (wp_newssync_item_map) |
+--------------------------------+
| wp_newssync_item_map           |
+--------------------------------+
```

✅ **Success!** Table created.

---

#### Option C: Manual SQL (No SSH Access)

**Requirements:**
- Access to phpMyAdmin or similar database tool
- Your WordPress database name and table prefix (usually `wp_`)

**Step-by-step:**

1. **Login to phpMyAdmin** (usually via hosting control panel)
2. **Select your WordPress database** (left sidebar)
3. **Click "SQL" tab** (top menu)
4. **Paste this SQL** (replace `wp_` with your table prefix):

```sql
CREATE TABLE IF NOT EXISTS `wp_newssync_item_map` (
  `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
  `guid` VARCHAR(191) NOT NULL,
  `post_id` BIGINT UNSIGNED NOT NULL,
  `feed_slug` VARCHAR(128) NULL,
  `created_at` DATETIME DEFAULT CURRENT_TIMESTAMP,
  PRIMARY KEY (`id`),
  UNIQUE KEY `guid` (`guid`),
  KEY `post_id` (`post_id`)
) DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```

5. **Click "Go"** (bottom right)
6. **Verify:** Look for "Query OK" message ✅

---

### 📊 Migrating Existing Data (Optional)

**If you already have imported items:** Migrate them to the new table for consistency.

**WP-CLI command:**

```bash
wp newssync migrate-item-map --batch=200
```

**What it does:**
- Reads existing `_newssync_guid` postmeta entries
- Copies them to the `newssync_item_map` table
- Processes in batches (safer for large datasets)

**Parameters:**
- `--batch=200` — Process 200 items at a time (adjust based on server)
- `--dry-run` — Preview changes without writing (test first!)

**Example output:**
```
Processing batch 1/10 (200 items)... Done.
Processing batch 2/10 (200 items)... Done.
...
Migration complete: 2000 items migrated.
```

⚠️ **Backup first!** Always backup your database before migrations.

---

## ❌ Troubleshooting

### Installation Issues

#### "Plugin could not be activated"

**Causes:**
- PHP version too old (requires 7.4+)
- Missing WordPress requirements
- File permissions incorrect

**Fixes:**
1. ✅ **Check PHP version:** Settings → Site Health → Info → Server
   - If < 7.4, contact hosting to upgrade
2. ✅ **Check file permissions:** Files should be `644`, folders `755`
3. ✅ **Check error log:** Enable WP_DEBUG (see below)

---

#### "Upload failed" or "Destination folder already exists"

**Fixes:**
1. ✅ **Delete old version:** Plugins → Deactivate → Delete → Try again
2. ✅ **Use FTP method:** Upload manually to `/wp-content/plugins/`
3. ✅ **Check disk space:** Contact hosting if server full

---

### Feed Display Issues

#### Feed shows "No items found"

**Causes:**
- Invalid feed URL
- Feed is empty/private
- Caching issue

**Fixes:**
1. ✅ **Test feed URL:** Open in browser (should show XML)
2. ✅ **Validate feed:** Use [W3C Feed Validator](https://validator.w3.org/feed/)
3. ✅ **Clear cache:** Settings → NewsSync → Force Refresh
4. ✅ **Try different feed:** Test with `https://wordpress.org/news/feed/`

---

#### Feed items look broken/unstyled

**Causes:**
- Theme CSS conflicts
- JavaScript errors
- Plugin conflict

**Fixes:**
1. ✅ **Switch to default theme:** Test with Twenty Twenty-Four
2. ✅ **Disable other plugins:** Test with only NewsSync active
3. ✅ **Check browser console:** Look for JavaScript errors (F12)

---

#### Images not showing

**Causes:**
- Feed doesn't include images
- Image URLs broken/expired
- Hotlink protection on source site

**Fixes:**
1. ✅ **Check feed has images:** View feed XML, look for `<enclosure>` or `<media:content>`
2. ✅ **Set default thumbnail:** Settings → NewsSync → Default Image

---

### Performance Issues

#### "Fatal error: Maximum execution time exceeded"

**Causes:**
- Processing too many feed items at once
- Slow external feed server
- Low PHP timeout limit (default 30 seconds)

**Fixes:**
1. ✅ **Reduce items:** Set `posts_per_page="10"` (not 100+)
2. ✅ **Increase timeout:** Contact hosting or add to `wp-config.php`:
   ```php
   set_time_limit(300); // 5 minutes
   ```
3. ✅ **Enable caching:** Settings → Cache Duration = 1 hour minimum

---

#### "Fatal error: Allowed memory size exhausted"

**Causes:**
- Too many items processed
- Low PHP memory limit (default 256MB)
- Large images in feed

**Fixes:**
1. ✅ **Increase memory:** Add to `wp-config.php`:
   ```php
   define('WP_MEMORY_LIMIT', '512M');
   ```
2. ✅ **Reduce items:** Use smaller `posts_per_page` value
3. ✅ **Create database table:** See Performance Optimization above

---

#### Pages load slowly with feeds

**Fixes:**
1. ✅ **Enable caching:** Settings → Cache Duration = 1 hour+
2. ✅ **Use CDN:** Cloudflare or similar for images
3. ✅ **Reduce items:** Show 5-10 items, add "Load More" button
4. ✅ **Use lazy loading:** Images load as user scrolls

---

### Database Table Issues

#### "Table creation failed"

**Causes:**
- Database user lacks CREATE privileges
- Database is full/quota exceeded
- MySQL version too old (requires 5.6+)

**Fixes:**
1. ✅ **Check privileges:** Contact hosting to grant CREATE permission
2. ✅ **Use manual SQL:** See Option C above (phpMyAdmin)
3. ✅ **Don't worry:** Plugin works without table (just slower)

---

#### "Migration failed" or timeouts during migration

**Fixes:**
1. ✅ **Reduce batch size:** `--batch=50` instead of 200
2. ✅ **Increase timeout:** See PHP timeout fixes above
3. ✅ **Run in chunks:** Migrate 500 items, wait, repeat
4. ✅ **Skip migration:** New imports will use table automatically

---

## 🐛 Enabling Debug Mode

**When support asks for logs:**

1. **Edit wp-config.php** (via FTP or hosting file manager)
2. **Add before `/* That's all, stop editing! */`:**
   ```php
   define('WP_DEBUG', true);
   define('WP_DEBUG_LOG', true);
   define('WP_DEBUG_DISPLAY', false);
   ```
3. **Save file**
4. **Reproduce the issue**
5. **Get log:** Download `/wp-content/debug.log`
6. **Share with support**

⚠️ **Disable debug mode after troubleshooting** — logs can grow large!

---

## 🆘 Getting Help

### Before asking for help:

1. ✅ **Check this guide** — Most issues covered above
2. ✅ **Test with default theme** — Rule out theme conflicts
3. ✅ **Disable other plugins** — Rule out plugin conflicts
4. ✅ **Enable debug mode** — Get error logs

### Support Channels

**Free Support:**
- 📖 **Documentation:** [https://daazlabs.com/newssync/docs/](https://daazlabs.com/newssync/docs/)
- 💬 **WordPress Forums:** [WordPress.org Support](https://wordpress.org/support/plugin/rss-newssync/)
- 🐛 **Bug Reports:** GitHub Issues (link in plugin)

**When posting for help, include:**
- WordPress version (Dashboard → Updates)
- PHP version (Settings → Site Health)
- NewsSync version (Plugins page)
- Feed URL you're trying to use
- Error message (if any)
- Debug log (if available)

---

## 🚀 Next Steps

**Now that NewsSync is installed:**

1. ✅ **Try different layouts** — Grid, List, Minimal
2. ✅ **Combine multiple feeds** — Use comma-separated URLs
3. ✅ **Customize styling** — Add custom CSS
4. ✅ **Explore PRO features:**
   - 🤖 AI-powered summaries
   - 📄 Full-text extraction
   - 🔍 Advanced filtering (regex, keywords)
   - 📊 Managed feeds (per-feed settings)
   - 📈 Usage analytics

**Upgrade to PRO:** [https://daazlabs.com/newssync/pro/](https://daazlabs.com/newssync/pro/)

---

## 📚 Related Documentation

- **[Shortcode Reference](https://daazlabs.com/newssync/docs/shortcodes/)** — All available options
- **[Styling Guide](https://daazlabs.com/newssync/docs/styling/)** — Customize appearance
- **[PRO Features](https://daazlabs.com/newssync/docs/)** — Advanced capabilities
- **[Developer Guide](https://daazlabs.com/newssync/docs/developers/)** — Hooks, filters, API

---

**🎉 Congratulations!** You've successfully installed NewsSync. Start aggregating RSS feeds and building amazing content! 🚀

---

**Last updated:** February 6, 2026
**Plugin Version:** 1.0.0+
**Requires:** WordPress 5.8+, PHP 7.4+