WordPress Playground lets anyone launch a live WordPress site instantly — no hosting or installation required. It's a quick, hands-on way to explore how a theme looks and behaves.
You can open a fresh WordPress instance with a single link and start experimenting right away.
If a theme is available in the WordPress repository, you can preview it in Playground by adding the theme's slug to the URL, for example:
?theme=kiosko.
That said, each Playground site starts with a clean WordPress install, so themes load with no existing pages or demo content.
If you want your theme to appear exactly as you've designed it — with sample content, navigation, and settings — you can use Playground Blueprints.
In this guide, I'll show you how to get started with Playground Blueprints and create a complete, interactive demo site for your theme.
For this exercise, you'll use a GitHub repository to store assets, such as .xml and blueprint.json files, to build your demo. For Playground to have access, it needs to be a public repository.
What are Playground Blueprints?
WordPress Playground Blueprints let you create preconfigured demo sites in JSON format.
Each Blueprint describes how the Playground instance should be built — what theme to install, what content to import, which settings to enable, and more.
You can browse the full documentation here: WordPress Playground → Blueprints
With Blueprints, you can share a single link that launches a fully configured demo of your theme — complete with pages, patterns, and media — so visitors can explore it directly in their browser.
Let's explore the process step by step.
1. Create your demo website content
First, build a demo version of your theme locally — complete with pages, posts, navigation, and settings — to show how it looks in a real site.
You'll later export this content and use it inside Playground.
If you've worked with the Site Editor before, this part will feel familiar. You already know what combination of pages, posts, navigation, images, and WordPress settings makes your theme shine.
For this post, I prepared a demo site using the Twenty Twenty-Five default theme, applying one of its style variations and modifying some templates.
The example mimics a travel blog demo with a homepage, blog page, about page, and example templates and patterns:
I've also included a 404 page template:
As well as an 'About Us' page:
And more.
2. Handle images and patterns
While you create your content, you might use Patterns that come with your theme.
Often, images used are part of the theme and stored in the theme's assets folder.
You would need to upload those to the Media Library and pull them from there into your pages or posts — or replace their URL references in the content with relative links pointing to:
/wp-content/themes/{yourtheme}/assets/{filename} …and remove the https://{domain.ext} part of the URL.
It's best to use WordPress tools to automatically add them to the Media Library to save or from the image block toolbar.
This gives you a self-contained content file you can reuse with other themes or Playground instances.
3. Export your content
Once you've built the demo content on your local site, export it using the WordPress Export feature:
Go to Tools → Export, and select All Content (or make specific choices).
You can learn more about the Export feature in the documentation.
Before importing the .xml file into Playground, make sure your images and other assets are ready.
You'll also need to update the image references in your content file.
4. Prepare your export for Playground
Before importing your exported .xml file, make sure Playground can access your media files and that all image links point to the correct locations.
To do this:
- Upload your demo images and assets to a public GitHub repository (for example, to a /media folder).
- Update the image references in your .xml file so they point to those GitHub URLs.
Upload your demo images and assets
Playground uses the WordPress Importer plugin, which automatically resizes images and updates URLs for the new site.
However, the importer tries to fetch images from their original URLs — and most web servers block these requests because of Cross-Origin Resource Sharing (CORS) policies.
To fix that, host your demo assets on GitHub.
GitHub's raw.githubusercontent.com domain bypasses these restrictions, making it ideal for serving demo media.
Upload all your images to a /media folder in your GitHub repository and keep their original filenames to speed up the import process.
Update the image references in your .xml file
Next, replace the image references in your .xml file with the new GitHub URLs, under the <wp:attachment_url> tag.
Use this pattern:
https://raw.githubusercontent.com/{organization}/{reponame}/{branch}/media/{filename} For example:
<wp:attachment_url><![CDATA[https://raw.githubusercontent.com/wptrainingteam/tt5-demo-blueprint/main/media/random-headshot-1.jpg]]></wp:attachment_url>
And here's what each part means:
- Organization: your GitHub organization (for example, wptrainingteam)
- Repository: your repo name (for example, tt5-demo-blueprint)
- Branch: main
- Folder: media
- Filename: the original file name
Search your .xml file for <wp:attachment_url> (keeping the <![CDATA[...]]> tags intact) and replace each reference with the correct GitHub URL.
Tip: In the Twenty Twenty-Five demo site example, there were 17 replacements in total.
Your integrated development environment (IDE) probably allows you to find the particular string in your .xml file, no matter how big it is. You might see other image references in the file when you use the same image in different sizes.
I added a small Bash script to the repo; you could modify and use it at your own risk.
The WordPress Importer will resize the new images from the attachment URLs and replace the references in other places. You only need to change each image reference once.
5. Create your Blueprint
Now that your demo content is ready, it's time to configure your Playground site using a Blueprint.
A Blueprint defines how Playground sets up your demo — which theme to install, which content to import, and which options to apply.
Understand the Blueprint structure
The Blueprint file has two main parts:
- Settings – placed in the root of the document.
- Steps – actions listed in an array that Playground runs in order.
You can learn more in the Blueprint documentation.
Here's an outline of a starter JSON file:
{ "$schema": "https://playground.wordpress.net/blueprint-schema.json", "login": true, ... more settings, "steps": [ { "step":"installTheme" { } }, { "step":"importWXR" { } } more steps... ] } The first line ($schema) is optional.
Adding it helps your IDE validate syntax, suggest properties, and catch possible errors.
Add basic settings
The first setting is "login": true.
If you don't need specific credentials, this shorthand automatically gives visitors admin access on the demo site.
If you prefer more control, review the Blueprint step documentation and the Blueprint Gallery for different scenarios.
Clean the default WordPress content
Each new WordPress install includes sample content — a post, a comment, and a page — which can interfere with your demo.
You can add a step to the Blueprint to remove the content by executing a WP-CLI command:
{ "step": "wp-cli", "command": "wp site empty --yes" }, Import your demo content
To import the content specifically, leverage the importWxr step — using the raw.githubusercontent.com domain to point to your *.xml file.
{ "step": "importWxr", "file": { "resource": "url", "url": "https://raw.githubusercontent.com/wptrainingteam/tt5-demo-blueprint/main/playgroundcontent.xml" } } Install and activate the theme
Next, install and activate the theme you want to demo.
It can come from the WordPress repository, a ZIP file, or a directory of theme files.
This example uses the default Twenty Twenty-Five theme:
{ "step": "installTheme", "themeData": { "resource": "wordpress.org/themes", "slug": "twentytwentyfive" }, "options": { "activate": true } }, Set Site options
You might also want to set a few Site options. You can use a step or the shorthand to setSiteOptions:
- For the links to category pages and navigation menus to work, you'll need to enable pretty permalinks.
- You can also set values for the blog name and description to make it more enticing.
- To fully set up your demo, you'll probably also want to configure your front page and blog page.
The snippet below shows how to implement these settings:
"setSiteOptions": { "blogname": "Twenty-Twenty-Five", "blogdescription": "The WordPress default theme", "show_on_front": "page", "page_on_front": 80, "page_for_posts": 26, "permalink_structure": "/%postname%/" } The numbers for page_on_front and page_for_posts match the post IDs in your imported content.
This works because the site was emptied before import.
Optional: Add plugins
You can also include plugins — for example, block collections or WooCommerce.
Here's the shorthand for installing the "Block Visibility," "Public Post Preview," and "Gutenberg" plugins and activating them.
To add more plugins, just add them to the array:
{ "plugins": [ "block-visibility","public-post-preview", "gutenberg" ] } Combine everything
Now that you've added each step, it's time to combine them into one complete Blueprint file.
This final JSON defines your entire demo site setup — from cleaning the default content to installing your theme, importing posts, and setting site options:
{ "$schema": "https://playground.wordpress.net/blueprint-schema.json", "login": true, "steps": [ { "step": "wp-cli", "command": "wp site empty --yes" }, { "step": "updateUserMeta", "meta": { "admin_color": "modern" }, "userId": 1 }, { "step": "installTheme", "themeData": { "resource": "wordpress.org/themes", "slug": "twentytwentyfive" }, "options": { "activate": true } }, { "step": "importWxr", "file": { "resource": "url", "url": "https://raw.githubusercontent.com/wptrainingteam/tt5-demo-blueprint/main/playground-content.xml" } }, { "step": "setSiteOptions", "options": { "blogname": "Theme Demo ", "blogdescription": "A preview of a theme", "show_on_front": "page", "page_on_front": 80, "page_for_posts": 26, "permalink_structure": "/%postname%/" } } ], "plugins": [ "block-visibility","public-post-preview", "gutenberg" ], } 6. Test your Blueprint
Before sharing your demo, test the Blueprint in Playground to confirm that every step runs correctly and your theme appears as intended.
Open your Playground URL to launch the demo site and check that:
- The theme installs and activates properly.
- All pages, posts, and menus from the .xml import display.
- Images load from the GitHub /media folder.
- Permalinks and front-page settings work as expected.
If something looks off, review your blueprint.json for typos or missing commas.
Blueprints are declarative, so even a small syntax issue can interrupt setup. Fix any issues locally, upload the corrected file to GitHub, and refresh the Playground link to test again.
7. Share your Blueprint
Finally, upload your blueprint.json file to GitHub and share the Playground URL with the Blueprint query parameter.
You can use a URL shortener such as Bitly to track usage.
For example:
https://playground.wordpress.net/?blueprint-url=https://raw.githubusercontent.com/wptrainingteam/tt5-demo-blueprint/main/blueprint.json
The complete theme demo is available on GitHub and includes:
- The content to import
- Images and assets in the /media folder
- The blueprint.json file
- The Bash script to help with the attachment URL replacements
Tip: The Blueprints documentation offers many ways to configure your Playground instance for your or your clients' needs.
Learn more about Blueprints and Playground
Now that you've learned how to use Playground to showcase your products, explore these guides on the WordPress Developer Blog:
You can also apply this knowledge in WordPress Studio, which now supports Blueprints.
0 Response to "How to Build an Interactive WordPress Theme Demo with Playground Blueprints"