WordPress Integration Guide

✅ Primary delivery adapter (un-deprecated 2026-06-20). WordPress is the primary delivery path for the remediation platform — the earlier "legacy / frozen / edge-first" stance was reversed when the adapter strategy went EU-aware (Cloudflare's CDN share is far lower outside the US; a plugin needs no CDN/DNS change and keeps us out of the visitor traffic path / GDPR). The plugin is being extended from publish-only into a remediation delivery adapter (HMAC-pull the signed bundle → apply() server-side). See REMEDIATION-PLATFORM.md §4a + §9 for the strategy. This guide covers connecting a WordPress site for publishing today.

This guide shows how to connect your WordPress site to Rankwise so that AI-generated articles can be pushed into your CMS as live posts with Elementor-safe formatting.

Plugin bundle: wordpress-plugin/rankwise-publisher (run npm run wp:package to zip)
WordPress.org: prepared for the plugin directory as slug rankwise-publisher (0.5.0, DEV-275), not yet submitted. npm run wp:package:wporg builds the directory zip without the self-hosted updater. Steps and the review checklist: growth/WPORG-SUBMISSION.md.

1. Prerequisites

WordPress 6.0+ with REST API enabled and administrator access.
Ability to upload custom plugins (or install from ZIP).
A Rankwise account with at least one integration slot.
WORDPRESS_CONNECT_SECRET configured in your Rankwise deployment — the shared secret used to HMAC-sign and verify short-lived connection tokens (see §Env Setup).
ARTICLE_IMAGES_ENABLED — kill switch for hero image generation. Set to false to disable image generation entirely (the generator throws image_generation_disabled); any other value (or unset) leaves generation enabled.
Optional: Elementor 3.x if you rely on Elementor blocks.

Env Setup

WORDPRESS_CONNECT_SECRET must be set or the connect-token code path throws (WORDPRESS_CONNECT_SECRET is not configured from lib/wordpress/auth.ts).

Local dev: add it to .env.local, e.g. WORDPRESS_CONNECT_SECRET=<random-string>.
Production: provide it as an SST secret (it is read from process.env at runtime).

Token TTL is 30 minutes by default and can be tuned with the optional WORDPRESS_CONNECT_TOKEN_TTL_MS.

2. Install the Rankwise Publisher plugin

From this repo, run npm run wp:package to create dist/rankwise-publisher.zip.
In your WordPress dashboard go to Plugins → Add New.
Click Upload Plugin, select rankwise-publisher.zip, then install and activate.
Enable Auto-updates for the plugin so future secret rotations do not break publishing.

3. Connect Rankwise to WordPress

One click (plugin 0.6.0 and later): in WordPress open Rankwise Publisher and click Connect with Rankwise. Sign in to Rankwise if asked, click Connect this site, and you land back in WordPress connected. Mechanism and security: PUBLISHING.md §6.

Or paste a token:

Open the Rankwise app dashboard → Integrations.
Select your WordPress site and click Connect site / Regenerate token.
Copy the short-lived token that appears in the modal.
In WordPress go to Rankwise Publisher → Settings, paste the token, and click Connect Site.
Rankwise opens a new tab confirming the integration plus the shared secret. Make sure the values shown in WordPress match what Rankwise lists.

The plugin's three AI-visibility features (IndexNow pings, AI-crawler telemetry, remediation) are opt-in since 0.5.0: tick them on the same settings screen. Nothing is sent anywhere on install or activation.

If you reinstall WordPress or rotate secrets, repeat the steps above. Each request triggers a new API key + shared secret pair.

4. Configure publishing defaults

Inside Rankwise → Integrations → Publishing Defaults you can tailor how content lands in WordPress:

Author: supply the numeric WP user ID that should own the post.
Categories / Tags: comma-separated lists sent with every publish.
Post vs. Page: pick whether content becomes a standard post or a top-level page.
Slug strategy: keep the generated title or force the article keyword as the slug.
Elementor compatibility: enable this if Elementor formats the page so the plugin sets the proper post meta (_elementor_edit_mode, etc.).

Save the configuration and it becomes the default for manual and automatic publishes.

Note: Rankwise always publishes live posts — there is no push-as-WP-draft mode. If you want to review content before it goes live, keep it in Rankwise (set the integration's publish mode to "Draft" so generated articles stay inside Rankwise instead of being pushed to your CMS — Autopilot drafts also wait in your review queue until approved) and publish when ready.

5. Publishing articles

Manual push

Generate or select an article in Rankwise.
Click Publish to WordPress in the preview pane or Publish in the list.
We enqueue a job, send the HTML + metadata via the plugin, store the returned WordPress post ID, and update the status to published once successful.

Automatic push

If the integration's publish mode is Live, Rankwise queues a publish job right after generation — for example when you approve an Autopilot draft. The UI shows progress and the published URL once the plugin responds. In Draft mode generated articles stay inside Rankwise — they are not pushed to WordPress until you publish them manually.

6. Troubleshooting

Symptom	Fix
`integration_not_connected` error	Ensure the plugin shows “Connected” and re-run the connect token flow to refresh secrets.
403 from plugin	Verify the API key + signature match (copy both from Rankwise → plugin settings). The Validate connection button on the integration detail page runs this exact check.
Articles not publishing automatically	Confirm the integration’s publish mode is `Live` (in `Draft` mode articles stay inside Rankwise).
Elementor layout broken	Enable the Elementor compatibility toggle in Rankwise so we set Elementor meta flags.
Token expired	Tokens last 30 minutes by default (see §1). Regenerate from Rankwise before attempting to connect.
Connection failed (HTTP 404) / endpoint_not_found	Plugin cannot reach the API. For local/staging, set `RANKWISE_PUBLISHER_REMOTE_URL` in wp-config.php to your app URL (see §8). For production, ensure the app is deployed and `/api/wordpress/sites` exists.

Still stuck? Email support@rankwise.sh with the failing site ID.

7. Production readiness checklist

Before pushing image generation + WordPress publish to production, confirm:

OPENAI_API_KEY, SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY, SUPABASE_STORAGE_BUCKET, NEXT_PUBLIC_SUPABASE_URL, WORDPRESS_CONNECT_SECRET are set in the production environment.
DB migration applied: 0023_article_wordpress_media.sql.
Supabase storage bucket article-images exists with correct visibility.
ARTICLE_IMAGES_ENABLED is set as intended (kill switch; false disables hero image generation).
OpenAI image model + size are the cost-optimized settings you expect.
Latest Rankwise plugin installed on the WordPress site (media route present).

8. Local dev overrides (wp-config.php)

If you need WordPress to talk to a local or ngrok Rankwise instance, you can override the Rankwise base URL in wp-config.php:

// Local Next.js (e.g. npm run dev on port 3000)
define('RANKWISE_PUBLISHER_REMOTE_URL', 'http://localhost:3000');

// Or ngrok / Cloudflare Tunnel for a remote WordPress reaching your machine
define('RANKWISE_PUBLISHER_REMOTE_URL', 'https://your-ngrok-url.ngrok-free.app');

If WordPress runs in Docker, use http://host.docker.internal:3000 so the container can reach the app on the host. A "Connection failed (HTTP 404)" or endpoint_not_found usually means the plugin is calling the wrong base URL.

This is a server-local WordPress config and is not part of this repo, so it does not get pushed with Rankwise code changes.

9. Resources

Plugin source: wordpress-plugin/rankwise-publisher
Packaging script: npm run wp:package (self-hosted zip, keeps the updater), npm run wp:package:wporg (WordPress.org zip, no updater)
Directory readme: wordpress-plugin/rankwise-publisher/readme.txt, including the External services disclosure

Publish Rankwise articles to WordPress