Headless Bridge for Rank Math
An independent, configurable WordPress bridge for Rank Math SEO, IndexNow and headless frontends, with optional editor links and CMS safeguards.
by Headless Bridge contributors · github.com/readyspace/rank-math-headless-bridge
Install
No release zip yet. The repository archive installs, but the folder name will carry the branch suffix and updates will not flow:
wp plugin install https://github.com/readyspace/rank-math-headless-bridge/archive/refs/heads/main.zipOne configurable WordPress plugin for sites that use Rank Math in the CMS and a separate public frontend.
Instead of maintaining a different helper plugin for every website, install the same version on each WordPress site and give each installation its own frontend address and enabled modules. For example, one installation can connect cms.example.com to www.example.com, while another connects a different CMS to a different public website.
Status: 0.1.0 alpha. This is an initial implementation for staging tests and community review. It is an independent, unofficial integration, not a Rank Math product. It does not bundle Rank Math. It does not install frontend code, deploy a website, migrate old helpers, or guarantee search-engine indexing.
Optional modules
All modules start disabled. Choose only the features your site needs.
| Module | Purpose | Frontend work needed |
|---|---|---|
| SEO URL mapping | Maps eligible CMS URLs in Rank Math structured data, canonicals, and social page addresses to the public frontend, preserving media and unrelated external URLs. | Inspect the rendered schema and your actual route layout. |
| Metadata endpoint | Exposes normalized SEO data for published, publicly readable posts through a read-only REST endpoint. | Render this data in server-generated page HTML. |
| IndexNow adapter | Adapts Rank Math's IndexNow submissions and verification-file location to the public frontend. | Deploy the current verification key file on that frontend. |
| Published editor links | Sends eligible published View links in the WordPress admin to the frontend. | Keep your existing authenticated preview integration. |
| CMS noindex | Adds noindex directives to the CMS while keeping frontend metadata generation separate. | Check the public frontend's robots directives independently. |
| WordPress mail suppression | Stops mail sent through wp_mail, unless an application explicitly allows a call. |
Confirm that disabling CMS mail suits your workflow. |
An ordinary WordPress website that already serves its public pages generally does not need this bridge. A headless site may already implement some of these features in its frontend or other plugins; avoid enabling overlapping implementations without testing.
Requirements
- WordPress 6.5 or newer and PHP 7.4 or newer.
- Rank Math installed separately for SEO and IndexNow modules.
- Rank Math Headless CMS Support enabled for the metadata endpoint, and the PHP DOM extension available.
- A separate configured frontend origin. Use its exact public origin, for example
https://www.example.com, without an article path, query string, or credentials. - A frontend that renders SEO data on the server. The WordPress plugin alone cannot place tags in a Next.js page.
- Pretty WordPress permalinks for the metadata, IndexNow, and editor-link modules in this first version.
- For IndexNow, Rank Math's Instant Indexing module and settings configured, a standard HTTPS frontend host, and a publicly accessible verification file on that host.
Rank Math's headless support documentation explains how to enable its native metadata provider. The bridge normalizes that provider's output; it does not replace Rank Math's SEO editor.
Install and configure
- Back up your CMS and test on staging, especially if other headless helper plugins are already active.
- Put this repository's plugin folder at
wp-content/plugins/rank-math-headless-bridge, or upload a release ZIP through WordPress. - Activate Headless Bridge for Rank Math.
- Open Settings → Headless Bridge. Set the frontend origin and choose the public post types that exist on the frontend.
- Enable modules individually and validate each one. Follow the migration guide when replacing existing plugins.
- Integrate the metadata endpoint into the frontend and, if needed, deploy the IndexNow key file.
The default route mapping preserves the path: https://cms.example.com/news/article/ becomes https://www.example.com/news/article/. If your frontend uses different routes, supply an explicit mapping and test it. This plugin does not discover a framework's route configuration automatically. WordPress's stored Home and Site URL settings are not changed.
Frontend example
For a public post with WordPress ID 123, request:
https://cms.example.com/wp-json/headless-bridge/v1/head?post_id=123The response contains normalized title, description, canonical, robots, Open Graph, Twitter, and JSON-LD fields. Drafts, private posts, password-protected posts, and excluded post types are unavailable through this endpoint. See the response contract and the Next.js examples.
The examples render explicit React tags and safely serialize JSON-LD. They do not inject Rank Math's raw head HTML. Keep the SEO request in your frontend's server-side rendering or build flow; fetching tags only after a browser loads the page is not an equivalent integration.
Important configuration choices
CMS noindex is a crawler directive, not access control. It does not hide or authenticate the CMS. An intentional Rank Math noindex setting on a post must still be respected by the frontend.
Mail suppression blocks WordPress mail, including password resets and administrative notices. Leave it disabled unless that is intentional and you have a working recovery process. Mail sent independently by an external service is outside this module's control.
Preview authentication remains with your preview provider. The published editor-link module does not forward WordPress nonces or passwords to the frontend and does not replace Faust's preview flow.
An accepted IndexNow submission is a notification, not proof of indexing. The key file must live on the host being submitted. The IndexNow protocol documentation describes verification and response codes.
Documentation and contributions
- Configuration and hooks
- Normalized metadata API
- IndexNow frontend setup
- Controlled migration and rollback
- Next.js examples
- Initial validation and remaining staging checks
- Contributing, security reporting, and changelog
The initial implementation generalizes the roles of site-specific SEO, IndexNow, editor-link, and CMS safeguard helpers. It is not a byte-for-byte consolidation of every existing plugin or a completed migration of any live site. Real-world compatibility reports, tests, framework adapters, and staged migration guides are welcome.
License
Original project code is licensed under GPL-3.0-or-later. Rank Math and framework dependencies remain separate projects with their own licensing and trademarks.