Using WordPress

WordPress connects to Makerkit as a headless CMS via its REST API. If you have existing WordPress content - blog posts, documentation, custom post types - you can use it directly without migration. Makerkit fetches content from WordPress at build time or request time, rendering it with your Next.js frontend while WordPress handles content management.

WordPress integration uses the WordPress REST API to fetch posts, pages, and custom content, treating WordPress as a headless content backend.

• Use WordPress when: you have existing WordPress content, your editors prefer the WordPress admin, or you need WordPress plugins for content workflows.
• Avoid WordPress when: you want Git-based content versioning, need offline editing, or prefer minimal infrastructure.

This page is part of the CMS Integration documentation.

Configuration

Set the environment variables to use WordPress:

CMS_CLIENT=wordpress
WORDPRESS_API_URL=https://your-wordpress-site.com

The WORDPRESS_API_URL should point to your WordPress installation's root URL (not the /wp-json/ endpoint - Makerkit appends that automatically).

Local Development with Docker

Makerkit includes a Docker configuration for local WordPress development:

# From the packages/cms/wordpress directory
docker-compose up

Or use pnpm:

pnpm --filter @kit/wordpress start

WordPress will be available at http://localhost:8080. Complete the WordPress installation wizard on first visit.

WordPress Configuration

Enable REST API Permalinks

The REST API requires pretty permalinks. In WordPress admin:

1. Go to Settings → Permalinks
2. Select Post name (or any option except "Plain")
3. Save changes

Without this, the REST API returns 404 errors.

Blog Posts Setup

Create blog posts that Makerkit can fetch:

1. Create posts in Posts → Add New
2. Assign posts to a category named blog
3. Publish the posts

Makerkit fetches posts from the blog category for the blog section.

Documentation Setup

WordPress pages don't have categories by default. Enable them by adding to your theme's functions.php:

// Enable categories for pages
function add_categories_to_pages() {
    register_taxonomy_for_object_type('category', 'page');
}
add_action('init', 'add_categories_to_pages');

Then create documentation pages:

1. Create pages in Pages → Add New
2. Assign pages to a category named documentation
3. Publish the pages

Multi-Language Content

For multi-language support, add language tags to posts:

1. Go to Posts → Tags
2. Create tags for each language: en, de, es, etc.
3. Tag each post with its language

Makerkit filters content by language tag when the language parameter is passed to getContentItems().

Common Pitfalls

• Permalink structure not set: The REST API requires pretty permalinks. "Plain" permalink structure breaks API requests.
• Category not created: Posts must have a blog category, pages must have a documentation category. Without these, content doesn't appear.
• CORS issues in development: If fetching from a different domain, configure WordPress CORS headers or use a proxy.
• Caching stale content: WordPress content is fetched at request time by default. Use Next.js ISR (revalidate) to balance freshness and performance.
• Forgetting PHP snippet for page categories: WordPress pages don't support categories out of the box. Add the functions.php snippet or use a plugin.
• REST API disabled by security plugin: Some WordPress security plugins disable the REST API. Allowlist the /wp-json/ endpoint if you're using such plugins.

Next: CMS API Reference →