Docs: Guide "WordPress Playground for Theme Developers"

[juanmaguitar]

As part of https://github.com/WordPress/wordpress-playground/pull/1602 there are plans to create a guides section where specific guides to tackle specific needs can be added to the docs.

To inaugurate this "Guides" section, I think a "WordPress Playground for Theme Developers" guide could be a good candidate. These are some of the ideas I think could be included as guidance for theme developers to leverage WordPress Playground for their work.

Playground for Theme Developers

• You can launch a WP Playground instance with any theme on the WordPress Themes Directory URL
  • Example: https://playground.wordpress.net/?theme=disco
• You can launch a WP Playground instance with any theme on a Github repo
  • Example: https://playground.wordpress.net/?blueprint-url=https://raw.githubusercontent.com/wordpress-juanmaguitar/tt4-dh-alternatives-custom-blocks/main/_playground/blueprint.json

see blueprint.json

``` { "$schema": "https://playground.wordpress.net/blueprint-schema.json", "landingPage": "/wp-admin/post.php", "preferredVersions": { "php": "8.0", "wp": "beta" }, "features": { "networking": true }, "steps": [ { "step": "installTheme", "themeZipFile": { "resource": "url", "url": "https://github-proxy.com/proxy/?repo=wordpress-juanmaguitar/tt4-dh-alternatives-custom-blocks&branch=main" }, "options": { "activate": true } }, { "step": "login", "username": "admin", "password": "password" } ] } ```

• You can launch a WP Playground instance with any initial content (including media) by importing XML that can be exported from any WordPress site
  • Example: https://playground.wordpress.net/?blueprint-url=https://raw.githubusercontent.com/wptrainingteam/tt4-book-reviews/master/_playground/blueprint.json

see blueprint.json

``` { "$schema": "https://playground.wordpress.net/blueprint-schema.json", "preferredVersions": { "php": "8.3", "wp": "latest" }, "features": { "networking": true }, "steps": [ { "step": "login" }, { "step": "installTheme", "themeZipFile": { "resource": "url", "url": "https://raw.githubusercontent.com/wptrainingteam/tt4-book-reviews/master/_playground/tt4-book-reviews.zip" }, "options": { "activate": true } }, { "step": "runPHP", "code": "query('delete from wp_posts');" }, { "step": "importWxr", "file": { "resource": "url", "url": "https://raw.githubusercontent.com/wptrainingteam/tt4-book-reviews/master/_playground/site-content.xml" } } ] } ```

• You can launch a Playground instance any theme from its folder code and using wp-now or Visual Code Studio extension

• With blueprints you can customize any initial setup you'd like for your theme

  • See some real-world examples for inspiration at blueprints gallery

Which key ideas should be reflected in this guide for Theme Developers? cc: @richtabor @ndiego @justintadlock @bph @mikachan

[richtabor]

Which key ideas should be reflected in this guide for Theme Developers?

When thinking about blueprints for themes, we should consider all the small parts that pull a theme demo together in full. Like setting show_on_front, assigning the page_on_front and page_for_posts, site logo (if it's possible), importWxr best practices, etc. Also installing related plugins (like blocks that a theme may leverage).

I did this for my blog's theme: https://github.com/richtabor/kanso/blob/main/blueprint.json (but not logo yet, it's not super clear the easiest way to do that).

Basically setting up a demo site only with playground.

[bph]

There is also a dev blog article in the works. The issue has a few discussion points. How to build a theme demo with WP Playground blueprints. It's on my to-do list for September.

[bph]

The Recap Hallway Hangout: Theme Building with Playground, Create-block-theme plugin, and GitHub has a video and some instructions on how to use Playground, CBT and GItHub for version control.

[adamziel]

Surfacing:

• https://github.com/WordPress/developer-blog-content/issues/272
• https://github.com/WordPress/wordpress-playground/issues/794
• https://github.com/WordPress/wordpress-playground/issues/759
• https://github.com/WordPress/wordpress-playground/issues/760
• https://github.com/Automattic/themes/pull/7928 (a theme PR created using just Playground)

Major points:

• You can preview a theme from the theme directory, GitHub repo, GitHub PR, or a local directory. If you set up the automated "Preview in Playground" comments you'll get a nice review workflow.
• You can make changes to that theme (via the create-block-theme plugin) and either export a zip or directly create / update a PR on GitHub.

CCing @beafialho @mikachan @vcanales

[adamziel]

Here's a Playground-based theme development workflow:

https://github.com/user-attachments/assets/907c6bce-f169-4ad5-aef7-ea49cfba91b8