# Substack Sync - User Guide

Welcome to Substack Sync! This plugin automatically imports your Substack newsletter posts into WordPress, making it easy to display your newsletter content on your website.

## What Does This Plugin Do?

Substack Sync automatically:
- Imports posts from your Substack newsletter RSS feed
- Downloads featured images from your posts
- Syncs new posts on a schedule you choose (hourly, twice daily, or daily)
- Displays your Substack posts anywhere on your WordPress site using shortcodes or blocks

## Quick Start Guide

### Step 1: Install and Activate
1. Upload the plugin to your WordPress site
2. Go to **Plugins** in your WordPress admin
3. Click **Activate** on "Substack Sync"

### Step 2: Configure Your Feed
1. In your WordPress admin, go to **Substack Posts → Settings**
2. In the **Feed URL** field, enter your Substack RSS feed URL:
   ```
   https://yourname.substack.com/feed
   ```
   (Replace "yourname" with your actual Substack username)
3. Click **Save Settings**

### Step 3: Import Your Posts
1. On the settings page, click the **Sync Now** button
2. Wait for the sync to complete (this may take a minute for the first import)
3. You'll see a success message when done

That's it! Your Substack posts are now in WordPress.

## Displaying Your Posts

There are three ways to display your Substack posts on your site:

### Method 1: Using a Shortcode (Easiest)

Add this shortcode to any page or post:
```
[substack_posts]
```

**Customize the display:**
```
[substack_posts count="5"]
```

**Available options (free):**
- `count` - Number of posts to show (default: 10)
- `orderby` - Sort by: date, title, modified (default: date)
- `order` - ASC or DESC (default: DESC)

**Pro options** (requires Substack Sync Pro):
- `columns` - Display in 2 or 3 columns
- `category` - Show only posts from a specific category

**Examples:**
```
[substack_posts count="10"]
[substack_posts count="10" orderby="title" order="ASC"]
```

### Method 2: Using Gutenberg Block Editor

1. Create or edit a page
2. Click the **+** button to add a block
3. Search for "Substack Posts"
4. Click the **Substack Posts** block
5. Use the block settings panel on the right to customize:
   - Number of posts
   - Sort order

> **Pro:** A Divi Builder module is available in [Substack Sync Pro](https://stormhillmedia.com/plugins/substack-sync-pro/).

## Key Settings Explained

### General Settings Tab

**Substack Feed URL**
- Your newsletter's RSS feed URL
- Format: `https://yourname.substack.com/feed`

**Sync Frequency**
- How often to check for new posts
- Options: Daily (free), Hourly / Twice Daily (Pro)
- Recommendation: Daily works well for most newsletters

**Posts Per Page**
- Default number of posts to display
- Can be overridden in shortcodes/blocks

**Handle Missing Posts**
- What to do when a post is removed from your Substack feed
- Options: Do Nothing, Move to Draft, Move to Trash
- Recommendation: "Move to Draft" (safest option)

### Content Settings Tab

**Content Display**
- **Excerpt Only** - Shows a summary of each post (recommended for lists)
- **Full Content** - Shows the entire post content

**Excerpt Length**
- Number of characters to show in excerpts
- Default: 300 characters

**Show Images in Excerpt**
- Toggle whether to include images in excerpts

**SEO Settings**
- **Add noindex meta tag** - Prevents duplicate content issues with search engines
- **Canonical link to Substack** - Points search engines to your original Substack post
- Recommendation: Enable both for best SEO

### Author Info Box Tab

Configure an optional author bio box that appears with your posts:

**Show Author Info**
- Toggle on to display author information

**Position**
- Top or Bottom of post content

**Style**
- Card, Minimal, or Banner layout

**What to Show**
- Avatar image
- Author description
- Subscribe button
- Avatar size

## Automatic Syncing

Once configured, the plugin automatically:
1. Checks your Substack feed for new posts (based on your schedule)
2. Imports any new posts it finds
3. Downloads featured images
4. Keeps everything up to date

You can also click **Sync Now** anytime to manually sync.

## Image Downloads

The plugin downloads featured images from your Substack posts automatically. Here's what happens:

1. **During Sync** - The plugin identifies featured images from your posts
2. **Background Download** - Images download in the background (doesn't slow down your site)
3. **Featured Images** - Downloaded images are set as WordPress featured images
4. **Automatic Retry** - If a download fails, it will retry automatically

### Repair Images Feature

If some posts are missing featured images:
1. Go to **Substack Posts → Settings**
2. Scroll to the **Repair Images** section
3. Click the **Repair Images** button
4. The plugin will check for downloaded images and attach them to posts

## Common Questions

### How do I change how posts look?

The plugin uses your theme's styling. You can customize the appearance with CSS in your theme or using a CSS plugin.

### Can I edit imported posts?

Yes! Imported posts work like regular WordPress posts. You can edit the content, add categories, change the featured image, etc.

### Will editing a post in WordPress affect my Substack?

No. The sync is one-way: Substack → WordPress. Changes in WordPress don't affect your Substack newsletter.

### What happens if I delete a post in WordPress?

The next sync will re-import it from Substack. If you want to permanently remove a post, delete it from Substack first.

### Can I import posts from multiple Substack newsletters?

Not with one installation. Each plugin installation syncs one Substack feed. You would need separate WordPress sites for multiple newsletters.

### Why aren't new posts showing up?

Check these things:
1. Make sure automatic syncing is enabled
2. Click **Sync Now** to manually sync
3. Check that your Substack feed URL is correct
4. Verify new posts appear in **Substack Posts → All Posts**

### How do I stop syncing?

Two options:
1. **Pause syncing** - In Settings, set Sync Frequency to a longer interval
2. **Stop completely** - Deactivate the plugin (your imported posts will remain)

## Viewing Your Imported Posts

To see all imported posts:
1. Go to **Substack Posts** in your WordPress admin menu
2. Click **All Posts**
3. Here you can view, edit, or manage all imported posts

Each post includes:
- Full content from Substack
- Original publication date
- Featured image (if available)
- Link to original Substack post
- Author information

## Advanced Features

### Category Import

The plugin can import Substack categories/tags:
1. Go to **Settings → Content Settings**
2. Enable **Import Categories from Substack**
3. Choose whether to use WordPress Categories or a custom taxonomy
4. New syncs will include category information *(Pro feature)*

### Shortcode Filtering

Display posts from specific categories:
```
[substack_posts count="10"]
```

### Multiple Display Styles

Create different displays on different pages:
```
<!-- Homepage: recent posts -->
[substack_posts count="6"]

<!-- Blog page: Full list -->
[substack_posts count="20"]

<!-- Sidebar: Latest 3 posts -->
[substack_posts count="3"]
```

## Troubleshooting

### Posts aren't syncing

1. **Check your feed URL** - Make sure it's correct (https://yourname.substack.com/feed)
2. **Click "Sync Now"** - Try a manual sync
3. **Check WordPress Cron** - Some hosts disable WP-Cron; contact your host if needed
4. **Review error logs** - Check with your host for any error messages

### Images aren't downloading

1. **Click "Repair Images"** - In the Settings page, use the Repair Images tool
2. **Check file permissions** - Your uploads folder needs write permissions
3. **Wait and retry** - Images download in the background; give it a few minutes
4. **Manual sync** - Click "Sync Now" to retry failed downloads

### Posts appear but with wrong formatting

The plugin preserves Substack's HTML formatting. If something looks off:
1. **Check your theme** - Different themes style content differently
2. **Use excerpts** - Try displaying excerpts instead of full content
3. **Add custom CSS** - Use your theme's custom CSS option to adjust styling

### Shortcode not working

Make sure:
1. You're using the exact shortcode: `[substack_posts]`
2. You're on a page that allows shortcodes (posts, pages, widgets usually work)
3. The plugin is activated
4. You have imported posts to display

## Best Practices

1. **Start with excerpts** - Use excerpt display for post lists, full content for single posts
2. **Enable SEO settings** - Prevent duplicate content issues with search engines
3. **Use reasonable sync frequency** - "Twice Daily" is usually perfect
4. **Test before going live** - Import and test display on a staging page first
5. **Keep featured images** - They make your posts much more engaging
6. **Use categories** - Organize your posts with categories for easier filtering

## Getting Help

If you need assistance:
1. Check this guide first
2. Review the plugin's settings page for built-in help
3. Contact your web developer for custom styling or advanced features

## Tips for Success

- **Consistent publishing** - Regular Substack posts = regular WordPress updates
- **Quality images** - Use good featured images in Substack for best results
- **Clear categories** - Organize your Substack with categories for better WordPress organization
- **Test post counts** - Try different counts to find what works best for your layout
- **Mobile preview** - Always check how posts look on mobile devices

---

## Quick Reference

**Default Shortcode:**
```
[substack_posts]
```

**Customized Shortcode:**
```
[substack_posts count="6"]
```

**Menu Locations:**
- Settings: **Substack Posts → Settings**
- View Posts: **Substack Posts → All Posts**
- Manual Sync: **Settings → Sync Now button**

**Minimum Requirements:**
- WordPress 5.0 or higher
- PHP 7.2 or higher
- Working WordPress cron (for automatic syncing)
- Your Substack RSS feed URL

---

**Version:** 1.1.0
**Last Updated:** February 2026

Thank you for using Substack Sync! We hope this plugin makes it easy to share your newsletter content with your website visitors.