igny8/docs/40-WORKFLOWS/CONTENT-PUBLISHING.md

Content Publishing Workflow Guide

Last Updated: January 20, 2026
Version: 1.8.4
Status: Production
Audience: Content Editors, Publishers, Site Administrators

---

Overview

This guide covers the complete content publishing workflow, from content creation through multi-platform publishing (WordPress, Shopify, Custom Sites). The system supports both immediate publishing and scheduled publishing with progress tracking and error recovery.

---

Publishing Workflow States

Content Status Flow

Draft → Review → Approved → Published

• Draft: Content is being written/edited
• Review: Content submitted for review by editors
• Approved: Content approved and ready for publishing
• Published: Content successfully published to site

Site Publishing Status

• not_published: Content has never been published
• scheduled: Content scheduled for future publishing
• publishing: Currently being published (in-progress)
• published: Successfully published to site
• failed: Publishing attempt failed (needs retry/reschedule)

---

1. Publishing from Approved Page

Single Content Publishing

Steps:

1. Navigate to Writer → Approved
2. Find the content you want to publish
3. Click the 3-dot menu on the content row
4. Select "Publish Now"
5. Publishing progress modal appears with real-time status:
   • 📄 Preparing content (0-25%)
   • 🚀 Uploading to site (25-50%)
   • ⚙️ Processing response (50-75%)
   • ✓ Finalizing (75-100%)
6. On success:
   • Green checkmark displayed
   • "View on [Site Name]" button available
   • Content marked as published
7. On failure:
   • Error message displayed
   • Retry button available
   • Close button to exit

Features:

• Real-time progress tracking
• Platform-agnostic (works with WordPress, Shopify, Custom sites)
• Automatic error recovery
• Direct link to published content
• No limit on single item publishing

Bulk Publishing (Max 5 Items)

Steps:

1. Navigate to Writer → Approved
2. Select 2-5 content items using checkboxes
3. Click "Publish to Site" button at top
4. Bulk publishing modal shows queue with individual progress bars
5. Items process sequentially (one at a time)
6. Each item shows:
   • Progress bar (0-100%)
   • Current status (Preparing/Uploading/Processing/Finalizing)
   • Success: Green checkmark + published URL
   • Failure: Red X + error message + Retry button
7. Summary at bottom: "X completed, Y failed, Z pending"
8. Cannot close modal until all items complete

Publishing Limit:

• Direct bulk publish: Maximum 5 items at once
• Reason: Prevents server overload and API rate limiting
• For more items: Use "Schedule Selected" instead (no limit)

If you select 6+ items:

⚠️ Publishing Limit Exceeded Modal appears:
- Shows you selected X items (over 5 limit)
- Options:
  1. Deselect items to publish ≤5
  2. Use "Schedule Selected" instead (no limit)
- Tip: Scheduling is better for large batches

---

2. Scheduling Content

Manual Scheduling (Single Item)

Steps:

1. Navigate to Writer → Approved
2. Click 3-dot menu on content row
3. Select "Schedule"
4. Schedule Content Modal appears:
   • Schedule Date: Pick date from calendar
   • Schedule Time: Set time (HH:MM AM/PM)
   • Preview: Shows "January 15, 2025 at 9:00 AM"
5. Click "Schedule" to confirm
6. Content appears in Publisher → Content Calendar
7. Celery task will auto-publish at scheduled time (runs every 5 minutes)

Default Time: 9:00 AM on selected date

Bulk Scheduling (Unlimited Items)

Steps:

1. Navigate to Writer → Approved
2. Select any number of items (no limit!)
3. Click "Schedule Selected" button
4. Bulk Schedule Preview Modal shows:
   • Your site's default schedule settings
   • Start time (e.g., 9:00 AM)
   • Stagger interval (e.g., 15 minutes between each)
   • First and last publish times
   • List of all items with scheduled times
5. Options:
   • "Change Settings": Opens Site Settings → Publishing tab in new tab
   • "Confirm Schedule": Applies schedule to all items
6. All items scheduled and appear in calendar

Site Settings Integration:

• Go to Sites → [Your Site] → Settings → Publishing tab
• Configure:
  • Auto-publish Schedule: Time of day (e.g., 9:00 AM)
  • Stagger Interval: Minutes between each (e.g., 15 min)
  • Timezone: Your site's timezone
  • Max Daily Publishes: Optional limit per day
• These defaults apply to bulk scheduling automatically

Example Schedule (10 items, 9 AM start, 15 min stagger):

1. First Article    → Jan 17, 9:00 AM
2. Second Article   → Jan 17, 9:15 AM
3. Third Article    → Jan 17, 9:30 AM
4. Fourth Article   → Jan 17, 9:45 AM
5. Fifth Article    → Jan 17, 10:00 AM
...
10. Tenth Article   → Jan 17, 11:15 AM

Scheduling from Content Calendar

Drag-and-Drop Method:

1. Navigate to Publisher → Content Calendar
2. Approved content appears in left sidebar
3. Drag content item to desired date on calendar
4. Item scheduled for 9:00 AM on that date automatically
5. Edit time if needed (see "Editing Schedules" below)

---

3. Managing Scheduled Content

Viewing Scheduled Content

Content Calendar View:

• Navigate to Publisher → Content Calendar
• Calendar shows all scheduled items by date
• Each item displays:
  • Title (truncated)
  • Site name
  • Scheduled time
  • Status badge (Scheduled/Publishing/Published/Failed)

List View Filter:

• Navigate to Writer → Approved
• Filter by site_status = 'scheduled'
• Shows all scheduled items in table format

Editing Schedules (Rescheduling)

From Calendar View:

1. Find scheduled item on calendar
2. Click Pencil icon (Edit Schedule) on item
3. Schedule Content Modal opens with current date/time pre-filled
4. Change date and/or time
5. Click "Reschedule"
6. Item moves to new date/time on calendar

From Approved Page:

1. Navigate to Writer → Approved
2. Click 3-dot menu on scheduled content
3. Select "Reschedule"
4. Change date/time in modal
5. Click "Reschedule"

From 3-Dot Menu:

• Reschedule: Change to new date/time
• Unschedule: Cancel schedule, keep as approved
• Publish Now: Skip schedule, publish immediately

Unscheduling Content

Steps:

1. Click 3-dot menu on scheduled content
2. Select "Unschedule"
3. Confirmation modal appears:

   ⚠️ Unschedule Content?
   Current schedule: Jan 15, 2025 9:00 AM
   [Cancel] [Unschedule]
   

4. Click "Unschedule" to confirm
5. Content returns to not_published status
6. Stays in Approved page, can be rescheduled or published directly

---

4. Handling Failed Publications

Identifying Failed Content

Visual Indicators:

• ❌ Red "Failed" badge
• 🕐 Shows original scheduled time
• 📄 Error message (truncated)
• 🔄 Retry options available

Where to Find Failed Items:

1. Content Calendar: Separate "Failed Scheduled Publications" section at top
2. Approved Page: Filter by site_status = 'failed'
3. Dashboard: "Failed Publications" widget (if configured)

Failed Item Display (Calendar)

┌──────────────────────────────────────────────────────┐
│ ❌ Failed Scheduled Publications (2)                 │
├──────────────────────────────────────────────────────┤
│ ⚠️ Article Title 1                                   │
│    Site: My WordPress Blog                           │
│    Scheduled: Jan 13, 2025 9:00 AM                   │
│    Error: Publishing API error: Invalid credentials  │
│    [Reschedule] [Publish Now]                        │
└──────────────────────────────────────────────────────┘

Viewing Error Details

Steps:

1. Click 3-dot menu on failed content
2. Select "View Error Details"
3. Error Details Modal shows:
   • Content title and site name
   • Original scheduled time
   • Failure timestamp
   • Full error message
   • Actions: Fix Site Settings / Publish Now / Reschedule

Recovering from Failed Publishing

Option 1: Publish Now

• Click "Publish Now" button
• Opens Publishing Progress Modal
• Attempts immediate republish
• On success: Content marked as published, error cleared
• On failure: Error message updated, stays as failed

Option 2: Reschedule

• Click "Reschedule" button
• Opens Schedule Content Modal
• Pick new date/time
• Content re-queued with status = 'scheduled'
• Celery will retry at new scheduled time

Option 3: Fix Site Settings

• Click "Fix Site Settings" button
• Opens Site Settings → Publishing tab
• Check API credentials, domain, platform settings
• Return to content and retry

Common Error Types

Error	Cause	Solution
Invalid credentials	API key wrong/expired	Update API key in Site Settings
403 Forbidden	Permissions issue	Check user role in site admin
Network timeout	Site unreachable	Check domain, retry later
Missing required field	Content incomplete	Edit content, fill required fields
Rate limit exceeded	Too many requests	Reschedule with longer intervals
Platform-specific error	WordPress/Shopify API issue	Check error details, consult platform docs

---

5. Publishing to Multiple Platform Types

Supported Platforms

1. WordPress Sites

   • Uses WordPress REST API
   • Requires Application Password
   • Supports posts, pages, custom post types
   • Categories and tags automatically synced

2. Shopify Sites

   • Uses Shopify Admin API
   • Requires API key and password
   • Supports products, blog posts, pages
   • Collections automatically assigned

3. Custom Sites

   • Uses custom REST API endpoint
   • Flexible authentication
   • Configurable field mapping
   • Platform-agnostic error handling

Platform Configuration

Go to: Sites → [Your Site] → Settings

Required Fields:

• Platform Type: Select WordPress / Shopify / Custom
• Domain: Your site URL (e.g., https://mysite.com)
• API Key: Platform-specific authentication key
• Additional Settings: Varies by platform

WordPress Example:

Platform Type: WordPress
Domain: https://myblog.com
API Key: xxxx xxxx xxxx xxxx xxxx xxxx
Username: admin

Shopify Example:

Platform Type: Shopify
Domain: https://mystore.myshopify.com
API Key: shpat_xxxxxxxxxxxx
Password: shppa_xxxxxxxxxxxx

Publishing Behavior by Platform

All platforms use the same unified publishing interface:

• Same progress modal
• Same error handling
• Same scheduling system
• Platform differences handled automatically in backend

---

6. Review Page Workflow (Approval Only)

Important: No Publishing from Review

Review Page Purpose: Content approval workflow only

Available Actions:

• ✅ Approve (single or bulk)
• ✅ View content
• ✅ Edit content
• ✅ Delete content
• ❌ Publish to Site (removed)

Why?

• Ensures content goes through proper approval workflow
• Prevents accidental publishing of unreviewed content
• Clear separation: Review → Approve → Publish

Workflow:

1. Writer creates content (Draft)
2. Writer submits for review (Review)
3. Editor reviews and approves (Approved)
4. Publisher publishes from Approved page (Published)

---

7. Best Practices

When to Publish Immediately

• ✅ Time-sensitive content (news, announcements)
• ✅ Small batches (1-5 items)
• ✅ Testing new content types
• ✅ Urgent fixes or updates

When to Use Scheduling

• ✅ Large batches (6+ items)
• ✅ Content with planned publish dates
• ✅ Avoiding rate limits
• ✅ Publishing during optimal times
• ✅ Automated publishing workflows
• ✅ Content calendar planning

Scheduling Tips

1. Use Site Defaults: Let system handle timing automatically
2. Stagger Publications: 15-30 minute intervals reduce load
3. Check Timezone: Ensure site timezone matches your expectations
4. Plan Ahead: Schedule content days/weeks in advance
5. Monitor Failures: Check failed items daily, fix issues promptly
6. Test First: Publish 1-2 items manually before bulk scheduling

Error Prevention

1. Verify Credentials: Test site connection before bulk operations
2. Check Content Quality: Ensure all required fields filled
3. Validate Images: Confirm images uploaded and accessible
4. Review Platform Requirements: WordPress categories, Shopify collections, etc.
5. Monitor Rate Limits: Don't schedule too many items at once
6. Backup Content: Export content before large publishing operations

---

8. Troubleshooting

Problem: Publishing is slow

Solution:

• Check network connection
• Verify site is responsive
• Use scheduling instead of bulk publish
• Check site server performance

Problem: All items failing with same error

Solution:

• Check Site Settings → API credentials
• Verify domain is correct and accessible
• Test site connection manually
• Check platform API status (WordPress.org, Shopify status page)

Problem: Items stuck in "publishing" status

Solution:

• Backend may be processing
• Wait 5-10 minutes (Celery runs every 5 min)
• Check backend logs for errors
• Contact system administrator if persists

Problem: Schedule times are wrong timezone

Solution:

• Go to Site Settings → Publishing
• Set correct timezone for your site
• Reschedule affected items
• Future schedules will use correct timezone

Problem: Site selector not updating calendar content

Solution:

• Refresh your browser (Ctrl+F5 or Cmd+Shift+R)
• This issue was fixed in latest update (Jan 2026)
• Calendar now automatically reloads when you change sites
• Check browser console for site change logs
• If problem persists, clear browser cache

What was fixed:

• Frontend: Fixed useEffect dependency in ContentCalendar.tsx
• Backend: Added site_id and site_status to ContentFilter
• All API queries now properly filter by selected site

Problem: Cannot see published content on site

Solution:

• Click "View on [Site Name]" link to verify URL
• Check site visibility settings (not private/draft)
• Clear site cache if using caching plugin
• Verify content published to correct site
• Check platform-specific visibility settings

Problem: Bulk publish limit blocking my workflow

Solution:

• Use "Schedule Selected" instead (no limit)
• Set up site default schedule for automation
• Or select ≤5 items at a time for immediate publishing

---

9. Keyboard Shortcuts

Shortcut	Action
Space	Select/deselect item in table
Shift + Click	Select range of items
Ctrl/Cmd + Click	Select multiple non-contiguous items
Esc	Close modal (when not publishing)
Enter	Confirm action in modal

---

10. Support and Resources

Getting Help

• Documentation: docs/40-WORKFLOWS/ (this guide)
• API Reference: docs/20-API/PUBLISHER.md
• Developer Docs: docs/30-FRONTEND/PUBLISHING-MODALS.md
• System Status: Check backend logs at /admin/system/logs/

Contact

• Technical Issues: Contact system administrator
• Content Questions: Contact editorial team
• Platform Setup: Contact site owner/administrator

---

Document Version: 1.0
Last Updated: January 2026
Status: Production Ready