Skip to Content
UsingHeadless mode

Headless mode

Use headless mode when your readers visit a different website than this WordPress install. Common setups:

  • This WordPress runs at cms.example.com and your blog is served from example.com by a Next.js, Astro, or other static front end.
  • This WordPress is the editorial backend for a single-page app or mobile app, and “the public website” is a marketing site at a separate domain.

Without headless mode, Structura assumes that this WordPress install is the public website. That assumption is true for the vast majority of installs but breaks in the setups above — AI suggestions ground on the WP front page (which is empty in headless), internal links Structura adds to new posts point at cms.example.com URLs nobody visits, and channel shares (LinkedIn, IndexNow, Slack) post the wrong URLs.

Before you start

You’ll need:

  • The full URL of your public website (e.g. https://example.com)
  • Admin access to wp-admin

If you publish from this WordPress to your front end via a CMS build pipeline (Vercel ISR, Astro Content Collections, etc.), make sure that integration is already running before turning on headless mode — Structura’s settings only describe what’s already deployed.

Steps

  1. In wp-admin, go to Settings → General → Public website.
  2. Toggle My public website lives elsewhere to on.
  3. Click Detect & auto-configure. Structura will:
    • Propose a public URL by stripping a cms. prefix from this install’s host (so cms.xerx.io → https://xerx.io).
    • Scrape that URL via Jina, propose a description and key pages.
    • Open a confirmation dialog showing the proposals.
  4. Review the proposals. Apply proposals writes them into the form — you can still edit each field before saving.
  5. Optional: tweak any of:
    • Description — a short paragraph used as a fallback when AI grounding can’t reach your homepage.
    • Key pages — the about, pricing, services, etc. pages Structura should consider linking to from new posts. The list is auto-detected from your nav; remove or rename rows as needed.
    • Post URL pattern — how Structura should compose URLs for posts published from this WordPress. The default Prefix swap ({publicUrl}/{lang}/blog/{slug}) matches the Structura-recommended layout; pick Custom template… if your front end uses a different scheme (e.g. /news/{year}/{slug}).
    • Default language for URLs — used when {lang} is in the URL pattern. Defaults to your WP site language.
  6. Click Save.

What happens next

Once headless mode is on:

  • AI grounding scrapes your public website, not WordPress. Suggestions reflect the brand and content readers actually see.
  • Internal links Structura adds to new posts point at the rewritten public URLs (e.g. https://example.com/en/blog/<slug>).
  • Channels that share post URLs (LinkedIn, Slack, webhooks) post the public URL.
  • IndexNow points at the public URL too — see the IndexNow channel page for the keyfile upload step that’s specific to headless installs.

The next time WordPress saves a post, the post URL Structura emits on structura/post/inserted will be the rewritten one. Existing posts keep whatever URL they had on their _structura_* meta — re-publishing isn’t necessary unless you want to refresh derived state.

Common issues

The “Detect & auto-configure” button stays disabled. That button only fires when there’s something to scrape — confirm the public URL field has a value or that this install’s host starts with cms. (the auto-derive trigger). Otherwise type the public URL manually first.

Quick setup says “scrape failed”. The most likely cause is the public site being protected (Vercel password, IP allowlist, basic auth). Add the URL manually, fill in description and key pages yourself, and save.

Channel previews still show cms.* URLs. Trigger a fresh publish — Structura only computes the rewritten URL at insert time, so the cached preview cards on existing posts won’t update until the post is re-saved or the channel sends a new event.

The IndexNow keyfile fails to verify. See the IndexNow troubleshooting section. The most common cause is the file not being reachable at the exact URL shown — usually a deploy still in flight, or the file in a subdirectory rather than the front-end’s public root.

  • IndexNow channel — keyfile upload + verify flow for headless installs.
  • Settings tour — overview of the rest of the General settings page.
  • How channels work — what Structura emits on each publish and which channels consume it.
Last updated on
Featured images & visualsCreate a persona