N
HeadlessCoreHeadless Core
Back to Home

WordPress Setup

Complete reference for the HeadlessCore WordPress theme, admin settings, custom post types, and integrations.

Theme location

wp-content/themes/wp-headless-theme/
├── functions.php              # Settings, core CPTs, GraphQL, webhooks, licensing
├── style.css                  # Theme metadata
├── class-tgm-plugin-activation.php
└── inc/
    ├── extended-cpts.php      # Shop, team, FAQ, pricing CPTs
    ├── demo-importer.php      # One-click sample content
    └── admin-dashboard.php    # Dashboard status widget

Required plugins

Installed via TGMPA on theme activation:

Plugin Purpose
WPGraphQL GraphQL API endpoint at /graphql
WPGraphQL JWT Authentication JWT tokens for draft preview mode

Optional:

Plugin Purpose
WPGraphQL for WooCommerce WooCommerce product fallback on shop page

Admin menu: Headless Core

All headless features live under Headless Core in wp-admin.

General settings

Field Purpose
Enable Headless Mode Redirects public WP theme views to Next.js URL
Next.js Frontend URL Base URL for revalidation webhooks and preview links
Logo URL Shown in Next.js header
Copyright text Footer text
Social links Facebook, Twitter, Instagram, LinkedIn, GitHub
Primary / Accent colors CSS variables on frontend

Home Page Layout

Selects which layout renders at / on Next.js. See Site Modes for all 8 options.

SEO & Analytics

  • Default meta description
  • Open Graph share image URL
  • Google Analytics measurement ID

Header & Footer styles

Choose glass, dark, or light for navigation bar and footer.

Maintenance mode

Shows a "Coming Soon" screen on Next.js for all visitors. Draft preview still works.

Multipurpose Site Profile

Hero copy, CTA, contact details, portfolio bio, and JSON fields for skills/timeline. Exposed via GraphQL as themeSettings.siteProfile.

Cache & Preview

Secret Next.js env var
Revalidation Secret REVALIDATION_SECRET
Preview Secret PREVIEW_SECRET

Contact Webhook URL

Optional Slack or Discord incoming webhook URL. On each contact form submission, WordPress POSTs a JSON payload:

{
  "text": "New contact from John Doe (john@example.com): Hello..."
}

Set in Headless Core → Settings → Contact Webhook URL.

Licensing

Optional RSA-signed license key for pro tier (removes frontend attribution, unlocks white-label branding and pro Gutenberg blocks). See Licensing.

Pro Gutenberg blocks

With a valid pro license, 22 blocks appear under the HeadlessCore category in the block inserter. See Content model — Pro Gutenberg blocks for the full list and attribute schemas.

Highlights:

Block Purpose
CTA Banner Heading, text, and button call-to-action
Hero Banner Large hero with heading, subheading, CTA, optional image
Feature Grid Icon cards for product/service highlights
Pricing Table Multi-column pricing comparison (JSON-driven)
FAQ Accordion Question/answer pairs
Steps Numbered how-it-works flow
Callout Info/success/warning/error notice box
Icon List Checkmark feature bullet list
Magazine Category Grid Per-category post grids for magazine/blog landing pages

Content built with pro blocks keeps rendering on the frontend even if the license lapses — only inserting new pro blocks requires an active key. Blocks render server-side in PHP and appear in GraphQL content as styled HTML for the Next.js BlockRenderer.

Demo content importer

Headless Core → Settings → Import Demo Content

One-click button that creates sample posts, services, projects, testimonials, team members, FAQ items, pricing plans, and shop products. Safe to run multiple times (skips duplicates).

Dashboard status widget

The HeadlessCore Status widget on the WordPress dashboard shows:

  • GraphQL endpoint reachability
  • Next.js frontend URL configuration
  • Revalidation secret status
  • Active home layout mode

Implemented in inc/admin-dashboard.php.

Custom post types

Core CPTs (functions.php)

Admin label Post type GraphQL Used by
Corporate Services service services Corporate, Business, Landing
Case Studies portfolio_item portfolioItems Corporate
Portfolio Projects project projects Portfolio
Testimonials testimonial testimonials Business
Contact Submissions contact_submission — (admin only) Contact form logs

Extended CPTs (inc/extended-cpts.php)

Admin label Post type GraphQL Used by
Shop Products headless_product headlessProducts Shop
Team Members team_member teamMembers Corporate
FAQ faq faqs Corporate
Pricing Plans pricing_plan pricingPlans Corporate

See Content Model for all meta fields.

Navigation

  1. Create a menu under Appearance → Menus.
  2. Assign it to Primary Navigation.
  3. Items appear in Next.js header via themeSettings.navigationMenu.

On-demand revalidation

When you publish or update content, WordPress POSTs to:

POST {NEXTJS_URL}/api/revalidate
{ "secret": "...", "path": "/blog/my-post", "tag": "post" }

Path mapping:

Post type Revalidated path
post /blog/{slug}
page /{slug}
service, portfolio_item /corporate
project /portfolio
testimonial /business
headless_product /shop
team_member, faq, pricing_plan /corporate

Theme setting changes trigger full layout revalidation (/ + theme-settings tag).

See API Routes for request/response details.

Preview in Next.js

The Preview button in the post editor opens:

{NEXTJS_URL}/api/preview?secret=...&slug=...&type=post|page

Requires:

  • Matching PREVIEW_SECRET in Next.js
  • WORDPRESS_AUTH_TOKEN (JWT) for draft GraphQL queries

Contact form

GraphQL mutation submitContactForm:

  1. Validates name, email, message
  2. Stores submission in Contact Logs CPT (admin only)
  3. Sends optional webhook notification
  4. Attempts wp_mail() to admin email

Headless redirect

When Enable Headless Mode is on, template_redirect sends public visitors to the Next.js URL. Editors still access wp-admin normally.

AI Content Tools (pro)

Headless Core → Settings → AI Content Tools — choose Claude or OpenAI and paste the matching API key. Adds a "AI Content Tools (Pro)" panel to the post editor sidebar for generating an SEO description (saved to the post excerpt) and featured-image alt text. Requires a valid pro license and edit_posts capability on every request — see AI Content Tools for the full write-up including why both checks are needed.

File reference

Concern File
Settings page functions.php
Core CPTs + GraphQL functions.php
Extended CPTs inc/extended-cpts.php
Demo importer inc/demo-importer.php
Dashboard widget inc/admin-dashboard.php
License verification functions.php
White-label branding (pro) inc/white-label.php
Pro Gutenberg blocks inc/pro-blocks.php
Search indexing (pro) inc/search.php
AI content tools (pro) inc/ai-tools.php
i18n / Polylang-WPML bridge inc/i18n.php