Docs: Guide "WordPress Playground for Theme Developers"

[juanmaguitar]

As part of #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": "<?php require '/wordpress/wp-load.php'; $wpdb->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:

• Creating a low-code block theme development workflow with WordPress Playground and the Create Block Theme plugin developer-blog-content#272
• Theme contribution workflow #794
• Playground as a theme review tool on WordPress.org #759
• Block theme builder on WordPress.org #760
• Adonay: add theme Automattic/themes#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:

Theme.editing.mp4

[juanmaguitar]

Closing this issue as per #1747 and #1732