WordPress Sync Engine - ContentMK Docs

The WordPress Sync Engine is a core service built into ContentMK — not a module. It provides a unified WordPress REST API client that all WordPress-related modules share. The Sync page is your control center for keeping ContentMK in sync with your WordPress site. It pulls articles from WordPress, tracks changes on both sides, and alerts you to conflicts.

Connection Setup

To connect a site to WordPress, navigate to the site’s Sync page and provide:

WordPress URL — Your site’s address (e.g., https://example.com)
Username — Your WordPress username
Application Password — A WordPress Application Password (available in WordPress 5.6+). Go to your WordPress dashboard under Users > Profile > Application Passwords to generate one.

Public posts can be read without credentials, but full sync (including drafts, private posts, and write operations) requires an Application Password.

We recommend creating a dedicated WordPress user account with the Editor role specifically for ContentMK. This keeps sync activity separate from your personal account in WordPress audit logs, and the Editor role provides the right level of access — enough to read and write posts without full administrator privileges.

ContentMK automatically detects whether your site uses the standard /wp-json/ endpoint or the ?rest_route= fallback format. This means sites running security plugins that block direct access to /wp-json/ work out of the box with no special configuration on your part.

Connection Status

The top-right corner of the Sync page shows your WordPress connection status:

WP Connected (green indicator) — WordPress credentials are configured and working
WP Not Connected (gray indicator) — No credentials configured, or the last connection test failed

If not connected, a link below the sync controls takes you to Site Settings to configure your WordPress credentials.

Sync Operations

Three buttons control sync operations on the Sync page:

Test Connection — Verifies that your stored WordPress credentials work. On success, it displays the site name and total post count. On failure, it shows an error message explaining what went wrong (invalid credentials, unreachable URL, etc.).
Refresh Status — Reloads the sync status from the database to show the latest state without running a new sync.
Sync Now — Opens a dropdown with two options:
- Incremental Sync — Only pulls posts modified since your last sync. This is faster and puts less load on your WordPress server.
- Full Sync — Re-checks every post on the WordPress site. More thorough, but takes longer on large sites.

Below the buttons, you can see when the last sync occurred and a link to auto-sync settings.

Real-Time Progress

When a sync is running, a progress bar appears showing:

The current article being processed (by title)
How many articles have been processed out of the total
A Cancel button to stop the sync at any time — articles already processed up to that point are kept

Sync Status Cards

Five summary cards below the sync controls show the current state at a glance:

Card	Color	Meaning
Total Tracked	—	How many articles are being tracked by the sync engine
Synced	Green	Articles that are in sync between ContentMK and WordPress
Need Pull	Blue	Articles updated on WordPress that need to be pulled down to ContentMK
Need Push	Amber	Local changes that will be pushed to WordPress (coming soon)
Conflicts	Red	Articles modified on both sides since the last sync

These cards update after every sync operation and give you a quick read on whether anything needs attention.

Sync State Tracking

Every synced entity has a per-field sync status:

State	Meaning
Synced	Local and WordPress versions match
Local ahead	You’ve made changes in ContentMK that haven’t been pushed to WordPress
WP ahead	The WordPress version has been updated since the last sync
Conflict	Both sides have been modified since the last sync

Conflict detection uses modified-since timestamps to compare local and WordPress versions.

Conflict Resolution

When ContentMK detects that an article has been changed both locally and on WordPress since the last sync, it creates a conflict. The Conflicts section appears between the status cards and the changelog whenever unresolved conflicts exist.

Each conflict entry shows:

The article title and when the conflict was detected
An expandable diff view showing exactly what changed

Click on a conflict to expand it and see the full details:

Field comparison — A side-by-side table highlighting differences in title, status, slug, and excerpt between your local version and the WordPress version.
Content diff — A line-by-line comparison of the article body with red highlighting for local content and green highlighting for the WordPress version.

Resolution Options

Three options are available per conflict:

Keep Local — Preserve your local changes and discard the WordPress version
Keep WordPress — Accept the WordPress version and overwrite your local changes
Skip — Defer the decision for later; the conflict stays on the page

For handling multiple conflicts at once, bulk actions at the top of the section let you resolve everything in one click: Keep All Local or Keep All WordPress.

Auto-Sync

ContentMK can automatically sync your WordPress content in the background at a configurable interval, so you do not have to remember to click Sync Now manually.

To configure auto-sync:

Go to Site Settings (or click the “Auto-sync settings” link on the Sync page)
In the WordPress Connection section, find the Auto-Sync Interval dropdown
Choose an interval:
- Off — No automatic syncing
- 5 minutes — Frequent checks, best for high-traffic editorial teams
- 15 minutes — The default; a good balance between freshness and server load
- 30 minutes — Lighter on server resources
- 60 minutes — Minimal background activity

When auto-sync is enabled, ContentMK runs an incremental sync at the chosen interval. If conflicts are found during an auto-sync, they appear on the Sync page for manual resolution — ContentMK never overwrites your content automatically when there is a disagreement.

Sync History

Below the conflict section, a history table logs all past sync operations for the site. Each row includes:

Sync type — Whether it was a full sync or an incremental sync
Timestamp — When the sync ran
Duration — How long the sync took to complete
Results — A breakdown of articles inserted, articles updated, conflicts found, and errors encountered

Color-coded status badges make it easy to scan the table:

Green — Sync completed successfully with no issues
Yellow — Sync completed but conflicts were found that need resolution
Red — Sync failed or encountered errors

Changelog

The changelog shows a timeline of individual sync changes, giving you a detailed audit trail of everything the sync engine has done.

Each entry displays:

The operation type (e.g., “Article Updated”, “Article Created”)
The entity type and ID affected
A relative timestamp showing how long ago the change occurred
The before and after data for the change, available when you expand the entry

Entries that have been undone are shown with strikethrough text and a “Reverted” badge, so you can see the full history including rollbacks. Non-reverted entries have an Undo button that lets you revert that individual change — restoring the article to its previous state.

Rate Limiting

The sync engine includes built-in rate limiting to avoid overwhelming your WordPress server. By default, it pauses for 300ms every 10 requests. You can adjust this in site settings if your server can handle more throughput or needs longer pauses between requests.

Field Selection

The sync engine uses the _fields= parameter on all GET requests to minimize payload size. Only the fields ContentMK actually needs are fetched from WordPress, reducing bandwidth and improving sync speed.

Silent Batch Mode

During bulk operations (like a full site sync), the engine uses silent batch mode — one summary notification at the end instead of per-item alerts. This keeps the UI clean during large imports.

Manual Import

Below the sync controls, a collapsed section labeled Manual Import provides fallback import methods for when WordPress sync is not available — for example, if the site has no REST API access or is not running WordPress at all. Click the section header to expand it.

CSV Import

Upload a CSV or TSV file to bulk-import articles. The wizard walks you through four steps:

Upload — Drag and drop or select your CSV/TSV file
Map Columns — Review automatic column mapping (ContentMK matches common column names like “title”, “url”, “status”) and choose how to handle duplicates
Preview — See exactly what will be imported before committing, with a chance to go back and adjust mappings
Import — Write the articles to your site’s database

Sitemap Import

Point ContentMK at a sitemap URL to discover all pages on a site:

Detect or enter URL — ContentMK auto-detects common sitemap locations (/sitemap.xml, /sitemap_index.xml), or you can enter a URL manually
Fetch — The sitemap is fetched and parsed to discover all pages
Configure — Choose content fetching options and duplicate handling (skip duplicates based on URL matching)
Import — The discovered pages are imported as articles

Import History

At the bottom of the Manual Import section, an Import History table shows all past imports for the site. Each row includes:

Date — When the import was run
Source — The file name or sitemap URL used
Articles imported — How many new articles were added
Duplicates skipped — How many were skipped because they already existed
Undo button — Removes all articles from that import in one action

When to Use Sync vs Manual Import

Scenario	Recommended Approach
WordPress site with API credentials	Sync — automatic, keeps data fresh
WordPress site without API access	Manual Import via Sitemap
Non-WordPress website	Manual Import via CSV or Sitemap
One-time bulk data load from a spreadsheet	Manual Import via CSV
Ongoing content tracking	Sync with auto-sync enabled