WordPress 6.x and the Playground team have fundamentally changed how we handle theme demos. In the past, if a client or a potential user wanted to see a theme in action, you had two choices: a static screenshot gallery or a bloated multisite staging environment that was a nightmare to maintain. Neither was ideal. However, with the introduction of Playground Blueprints, we can now ship fully functional, interactive WordPress environments directly in the browser with zero server overhead.
But here is the catch: if you just point Playground to your theme slug, you get a “Hello World” site that looks nothing like your pro design. To build something that actually converts, you need a pre-configured environment. I’ve spent enough time debugging race conditions in transient environments to know that a solid Blueprint is the only way to go. If you are tired of staging sites, you should read my take on WordPress Playground in 2025.
Why Playground Blueprints Matter for Theme Devs
A Blueprint is essentially a JSON-based recipe. It tells Playground exactly how to bake the WordPress instance: which plugins to activate, what theme to set as active, and—most importantly—what content to import. Without Playground Blueprints, your demo is just a skeleton. With them, it is a high-fidelity experience.
1. Preparing Your Demo Content
First, you need a local “source of truth.” Build your site locally using the Site Editor. Once your navigation, patterns, and style variations are locked in, use the native WordPress Export tool (Tools → Export) to grab your WXR file.
The “Gotcha”: Playground instances are transient and run in a browser sandbox. They cannot reach back into your local localhost to grab images. You must host your assets on a public repository. As I discussed in my guide on WordPress GitHub Repositories, using GitHub for asset delivery is a pro move here.
2. The Media URL Replacement Hack
Before importing your XML into Playground, you must refactor the attachment URLs. Most servers block cross-origin requests (CORS), but GitHub’s raw.githubusercontent.com is a safe haven. You can use a simple Bash script to automate this replacement in your XML file:
# Example of updating attachment URLs in WXR
sed -i 's|https://your-local-site.test/wp-content/uploads/|https://raw.githubusercontent.com/username/repo/main/media/|g' demo-content.xmlStructuring Your Playground Blueprints JSON
The blueprint.json file consists of global settings and a steps array. Each step is executed sequentially. For a theme demo, we usually want to wipe the default “Hello World” content first using WP-CLI.
{
"$schema": "https://playground.wordpress.net/blueprint-schema.json",
"login": true,
"steps": [
{
"step": "wp-cli",
"command": "wp site empty --yes"
},
{
"step": "installTheme",
"themeData": {
"resource": "wordpress.org/themes",
"slug": "twentytwentyfive"
},
"options": { "activate": true }
},
{
"step": "importWxr",
"file": {
"resource": "url",
"url": "https://raw.githubusercontent.com/user/repo/main/playground-content.xml"
}
},
{
"step": "setSiteOptions",
"options": {
"blogname": "Pro Theme Demo",
"show_on_front": "page",
"page_on_front": 80
}
}
]
}In the example above, page_on_front refers to the ID of the page imported in your XML. Since we ran wp site empty, these IDs stay consistent, which is a lifesaver for automation.
Testing Your Blueprint
Once your JSON and XML are committed to GitHub, you can launch your demo via a URL parameter. Specifically, use the following structure:
https://playground.wordpress.net/?blueprint-url=https://raw.githubusercontent.com/user/repo/main/blueprint.json
Check the console for any transient errors. If your images aren’t loading, 99% of the time it’s a CORS issue or a typo in your GitHub raw URL. For deeper technical specs, always check the official Blueprints documentation.
Look, if this Playground Blueprints stuff is eating up your dev hours, let me handle it. I’ve been wrestling with WordPress since the 4.x days.
The Final Takeaway
Interactive demos aren’t a luxury anymore; they are the standard. By leveraging Playground Blueprints, you provide a frictionless way for users to touch your code before they buy it. Refactor your demo workflow today—your conversion rates will thank you.
Leave a Reply