Aribu js

Posted on Jun 27 • Originally published at shcho-i-yak.pp.ua

WordPress.com as a Headless CMS for Eleventy: A Practical Integration Guide

#tutorial #wordpress #javascript #jamstack

Step-by-step guide to building a decoupled Jamstack stack: WordPress.com as a Headless CMS powering an Eleventy static frontend via REST API. Honest breakdown of pricing, limits, and webhook automation.

BLUF

Problem: Pure static Eleventy blogs are blazing fast but miserable to edit on the go - no mobile UI, no non-technical contributor access, no quick fixes without a terminal.

Solution: Decoupled architecture. Remove physical Markdown post files from the Git repo entirely. Write content in WordPress.com's cloud Gutenberg editor; Eleventy fetches it via REST API at build time.

Cost: Full automation with webhook deploys is now available on the Personal plan at $4/mo (as of April 2026 - plugin access opened to all paid tiers).

Why Pure Static Can Feel Like a Trap

I genuinely love the Jamstack architecture. My own blog runs on Eleventy, built on Linux, written in VS Code, deployed to a VPS via custom Git hooks. TTFB sits around 48ms. Zero attack surface.

But let's be honest: the editorial experience of a pure static site is a disaster the moment you step away from your laptop.

Need to fix a typo from your phone? Want a non-technical co-author to publish a post independently? You're now in a flow that requires: opening the laptop, creating a .md file, hand-writing YAML frontmatter, pushing to the repo, waiting for the CI/CD pipeline. That's not a content workflow - that's a development workflow with a byline.

The usual fixes are expensive: self-hosted Strapi adds infrastructure overhead, Contentful and Sanity charge serious SaaS money. But WordPress.com ships a fast, globally-cached WP REST API out of the box, free. Let's use it.

Step 1: Set Up the Cloud Content Backend on WordPress.com

First, the thing that breaks the stereotype: you don't need a server or a MySQL database to use WordPress.com as a headless API backend. Automattic runs the infrastructure - SSL, security updates, CDN edge caching - entirely on their side.

Create a clean subdomain (e.g. yoursite.wordpress.com) on the Free or Personal plan. Navigate to Posts → Add New - you want Posts, not Pages, since we're building a blog feed.

The cloud Gutenberg editor opens. Write your content, add a Featured Image in the right sidebar, hit Publish. The post immediately becomes part of the cloud index and available via the API.

Gutenberg handles code blocks, nested lists, and media without touching Markdown syntax or writing custom Nunjucks shortcodes.

Step 2: Inspect the Data via WP REST API

WordPress.com provides a public API gateway that serves published posts without any OAuth flow for public content. Open a browser tab and hit:

https://public-api.wordpress.com/wp/v2/sites/yoursite.wordpress.com/posts

You'll get a JSON array. Each object contains everything Eleventy needs:

title.rendered - post title, HTML-safe
content.rendered - post body, compiled by Gutenberg into valid HTML
excerpt.rendered - auto-generated excerpt
date - ISO 8601 timestamp
link - canonical URL on WordPress.com

Note that content.rendered arrives as ready-to-render HTML, not Markdown. Eleventy's template engine doesn't need to parse anything - it just injects the string. Images in the content are automatically converted to absolute URLs pointing to Automattic's global media CDN (i0.wp.com). No regex path-replacement needed.

Step 3: Write the Node.js API Connector in Eleventy

Eleventy's Global Data Files mechanism is perfect for this. Any JavaScript file inside _data/ auto-exports its return value as a global variable available throughout the project.

Create _data/wpposts.js:

// _data/wpposts.js - Headless WordPress.com API Connector for Eleventy

module.exports = async function() {
  try {
    const res = await fetch(
      "https://public-api.wordpress.com/wp/v2/sites/yoursite.wordpress.com/posts?per_page=5"
    );

    if (!res.ok) {
      throw new Error(`WordPress.com API responded with status: ${res.status}`);
    }

    const posts = await res.json();

    return posts.map(post => {
      // Basic XSS sanitization before using | safe in Nunjucks templates
      const cleanContent = post.content.rendered
        .replace(/<script\b[^<]*(?:(?!<\/script>)<[^<]*)*<\/script>/gi, "");
      const cleanExcerpt = post.excerpt.rendered
        .replace(/<script\b[^<]*(?:(?!<\/script>)<[^<]*)*<\/script>/gi, "");

      return {
        title: post.title.rendered,
        link: post.link,
        date: post.date,
        excerpt: cleanExcerpt,
        content: cleanContent,
      };
    });

  } catch (err) {
    // Safe fallback - prevents the Eleventy build from crashing on network errors
    console.error("❌ Failed to fetch content from WordPress.com:", err);
    return [];
  }
};

A few notes on this connector:

The <script> strip is necessary. When you pipe third-party API HTML through Nunjucks's | safe filter, you're opting out of auto-escaping. The regex removes script injection vectors before the string ever hits the template.

The empty-array fallback matters. If WordPress.com is unreachable at build time, your Eleventy build won't crash - it just renders with no posts. For a CI/CD pipeline, this is the correct failure mode.

Now create a test page headless-test.njk in the project root:

---
layout: base.njk
permalink: /headless-test/
eleventyExcludeFromCollections: true
robots: "noindex, nofollow"
---

{% raw %}<ul>
{% for post in wpposts %}
  <li>
    <h2>{{ post.title }}</h2>
    <time>{{ post.date }}</time>
    <div>{{ post.content | safe }}</div>
  </li>
{% endfor %}
</ul>{% endraw %}

Run npm start. Eleventy fetches from Automattic's infrastructure, parses the JSON, and generates a static page at localhost:8080/headless-test/. The noindex meta tag keeps it out of search indexes - this is a dev route, not a production page.

Real Limitations: What This Stack Can't Do (Yet)

This is not a free magic solution. Here are the actual infrastructure constraints.

1. Automatic Deploy Triggers

Since Eleventy is a static generator, publishing a post in Gutenberg doesn't automatically rebuild your live site on Netlify or your VPS. You need to trigger an inbound deploy webhook.

Previously this was the main criticism of WordPress.com for headless use - outbound webhooks and automation plugins required the expensive Business plan. The April 2026 platform update changed this: full access to 50,000+ plugins is now available on all paid tiers including Personal ($4/mo). Install a plugin like WP Webhooks, connect it to your Netlify Build Hook URL, and you have a fully automated Jamstack pipeline for the price of a coffee per month.

2. Media Storage Caps

In the headless model, all images are hosted on WordPress.com's CDN and your Eleventy pages link to them. Storage limits apply:

Free plan: minimal storage - not viable for a real content project
Personal ($4/mo annual): 6 GB - sufficient for a technical blog with moderate image use
Business ($25/mo): 200 GB - for media-heavy publications

3. Raw Server Access

If you need direct MySQL access, SSH/SFTP tunneling, custom PHP session management, or background workers, you'll need the Business plan ($25/mo). The Personal plan covers 95% of content automation needs via plugins, but it's not a full VPS replacement.

WordPress.com Pricing Reference (June 2026)

Plan	Annual (per month)	Monthly	Key Features for Headless Use
Free	$0	$0	`.wordpress.com` subdomain, WP REST API, no plugins
Personal	$4	$9	Custom domain, 6 GB storage, 50,000+ plugins, ad-free
Premium	$8	$18	13 GB storage, VideoPress, plugins
Business	$25	$40	SFTP, PHP access, 200 GB storage
Commerce	$45	$70	WooCommerce, payments, 200 GB, priority support

For a headless setup, Personal is the practical entry point - it unlocks plugin access for deploy automation and provides enough storage for a technical blog.

FAQ

How do I pass custom SEO meta tags from WordPress.com into Eleventy?

As of the April 2026 update, you can install Yoast SEO or use Jetpack SEO on any paid plan. Both plugins add their metadata objects directly to the REST API response. In wpposts.js, map the post.yoast_head_json field and inject it into the <head> block of your base Nunjucks layout.

Can I implement category-based pagination in Eleventy from WordPress data?

Yes. The REST API returns an array of category IDs for each post. Using Eleventy's eleventyComputed and the built-in pagination feature, you can have the generator automatically create physical HTML category pages (e.g. /category/development/) and assign corresponding Eleventy tags at build time.

What happens to relative image links inside post content?

The public-api.wordpress.com gateway automatically converts all internal relative image URLs from Gutenberg into absolute URLs pointing to Automattic's global media CDN (i0.wp.com or files.wordpress.com). No custom regex path replacement needed - Eleventy receives fully resolved, render-ready links.

Verdict

WordPress.com as a headless backend directly undercuts overpriced SaaS CMS platforms like Contentful and Sanity for the indie developer use case. You get a production-ready, secured admin interface with the best visual editor in the ecosystem - in minutes, without any server setup risk, starting from free.

The April 2026 pricing reform - opening plugin access to Personal-tier accounts - makes this stack a genuine option for solo developers and small teams. Automated deploys via webhooks at $4/mo, combined with Eleventy's sub-50ms TTFB frontend, is a hard combination to beat at that price point.

Worth trying on your next Jamstack project.

DEV Community