From e01f1248e1ec26b502872a778090416836f97ef7 Mon Sep 17 00:00:00 2001 From: Fellyph Cintra Date: Wed, 15 Apr 2026 12:04:26 +0100 Subject: [PATCH 01/12] adding custom css for fallback --- packages/docs/site/src/css/custom.css | 79 +++++++++++++++++++++++++++ 1 file changed, 79 insertions(+) diff --git a/packages/docs/site/src/css/custom.css b/packages/docs/site/src/css/custom.css index 1854e1012d0..ab99a63c566 100644 --- a/packages/docs/site/src/css/custom.css +++ b/packages/docs/site/src/css/custom.css @@ -17,6 +17,12 @@ --ifm-color-primary-light: #526eec; --ifm-color-primary-lighter: #5f79ed; --ifm-color-primary-lightest: #869af2; + --wp--preset--color--acid-green-3: #b8e6bf; + --wp--preset--color--blueberry-4: #d7dffa; + --wp--preset--color--lemon-3: #faf2bf; + --wp--preset--color--pomegrade-3: #facfc6; + --wp--preset--color--charcoal-1: #1e1e1e; + --wp--preset--font-size--small: 0.875rem; } /* For readability concerns, you should choose a lighter palette in dark mode. */ @@ -190,3 +196,76 @@ a.navbar__link--active:hover { display: inline-block; } } + +/* + * WordPress.org design-system color tokens used by .callout below. + * These mirror the `--wp--preset--color--*` palette from wporg themes. + */ + +.callout { + --wp--custom--wporg-callout--color--background: var( + --wp--preset--color--acid-green-3 + ); + --wp--custom--wporg-callout--color--text: var( + --wp--preset--color--charcoal-1 + ); + background-color: var(--wp--custom--wporg-callout--color--background); + border-radius: 2px; + border-width: 0; + color: var(--wp--custom--wporg-callout--color--text); + font-size: var(--wp--preset--font-size--small); + padding: 1.25em 1.25em 1.25em 3.25em; + margin-bottom: 1.5em; + overflow: auto; + position: relative; + min-width: 170px; + + &:before { + background-image: url(data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMjQiIGhlaWdodD0iMjQiIGZpbGw9Im5vbmUiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyI+PHBhdGggZmlsbC1ydWxlPSJldmVub2RkIiBjbGlwLXJ1bGU9ImV2ZW5vZGQiIGQ9Ik0xOS42IDEyYTcuNiA3LjYgMCAxIDEtMTUuMiAwIDcuNiA3LjYgMCAwIDEgMTUuMiAwem0xLjQgMGE5IDkgMCAxIDEtMTggMCA5IDkgMCAwIDEgMTggMHptLTkuOSAxLjkwNnYuMDg2aDEuMjk3di0uMDg2Yy4wMDYtLjM0Ny4wNDUtLjYzOS4xMTctLjg3NS4wNzMtLjIzNS4xODgtLjQ0LjM0NS0uNjEyYTMuMDYgMy4wNiAwIDAgMSAuNjI2LS40OThjLjI3Mi0uMTYzLjUwNC0uMzUuNjk4LS41NjMuMTk2LS4yMTEuMzQ3LS40NTEuNDUzLS43Mi4xMDYtLjI3Mi4xNTktLjU3OC4xNTktLjkxNiAwLS40OTMtLjExNy0uOTIzLS4zNS0xLjI5MmEyLjMxMiAyLjMxMiAwIDAgMC0uOTctLjg2NmMtLjQxNi0uMjA5LS45MDMtLjMxMy0xLjQ2LS4zMTMtLjUwNyAwLS45Ny4wOTctMS4zOS4yOWEyLjQxMiAyLjQxMiAwIDAgMC0xLjAwNy44NTdjLS4yNTQuMzc1LS4zOTIuODM0LS40MTMgMS4zNzhoMS4zNzhjLjAyMS0uMzIuMTAxLS41ODEuMjQtLjc4NC4xNC0uMjA2LjMxNS0uMzU3LjUyNi0uNDUzLjIxMi0uMDk3LjQzNC0uMTQ1LjY2Ny0uMTQ1LjI1NyAwIC40OS4wNTQuNjk4LjE2My4yMTIuMTA2LjM4LjI1Ny41MDguNDUzLjEyNy4xOTcuMTkuNDMuMTkuNjk4IDAgLjIyNC0uMDQyLjQyOC0uMTI3LjYxMi0uMDg0LjE4NS0uMi4zNDgtLjM0NC40OS0uMTQ1LjE0Mi0uMzA5LjI3LS40OS4zODUtLjI4MS4xNy0uNTIxLjM1Ny0uNzIuNTYzLS4yLjIwNS0uMzU0LjQ3NC0uNDYzLjgwNi0uMTA2LjMzMy0uMTYyLjc4LS4xNjggMS4zNDJ6bS4wNDUgMi41OGEuODguODggMCAwIDAgLjY0LjI2M2MuMTY2IDAgLjMxNy0uMDQxLjQ1My0uMTIzYS45MzguOTM4IDAgMCAwIC4zMjYtLjMyNi44NjQuODY0IDAgMCAwIC4xMjctLjQ1OC44NS44NSAwIDAgMC0uMjcyLS42MzUuODY3Ljg2NyAwIDAgMC0uNjM0LS4yNjcuODcyLjg3MiAwIDAgMC0uNjQuMjY3Ljg1OC44NTggMCAwIDAtLjI2Ny42MzVjMCAuMjUxLjA5LjQ2Ni4yNjcuNjQ0eiIgZmlsbD0iIzAwOEEyMCIvPjwvc3ZnPgo=); + background-repeat: no-repeat; + content: ''; + position: absolute; + height: 24px; + left: 1em; + top: 1.25em; + width: 24px; + } + + & > *:last-child { + margin-bottom: 0; + } + + &.callout-info { + --wp--custom--wporg-callout--color--background: var( + --wp--preset--color--blueberry-4 + ); + + &:before { + background-image: url(data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMjQiIGhlaWdodD0iMjQiIGZpbGw9Im5vbmUiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyI+PHBhdGggZmlsbC1ydWxlPSJldmVub2RkIiBjbGlwLXJ1bGU9ImV2ZW5vZGQiIGQ9Ik0xOS42IDEyYTcuNiA3LjYgMCAxIDEtMTUuMiAwIDcuNiA3LjYgMCAwIDEgMTUuMiAwem0xLjQgMGE5IDkgMCAxIDEtMTggMCA5IDkgMCAwIDEgMTggMHptLTkuNzEzLTIuMjI2djcuMjU5aDEuNDEyVjkuNzc0aC0xLjQxMnptLjA4LTEuMzY1YS44OTguODk4IDAgMCAwIC42MzMuMjQ1Ljg4Mi44ODIgMCAwIDAgLjYyOS0uMjQ1Ljc5Mi43OTIgMCAwIDAgLjI2NC0uNTk2Ljc4My43ODMgMCAwIDAtLjI2NC0uNTk1Ljg3My44NzMgMCAwIDAtLjYyOS0uMjUuODg5Ljg4OSAwIDAgMC0uNjMzLjI1Ljc5Ljc5IDAgMCAwLS4yNi41OTVjMCAuMjMuMDg3LjQyOS4yNi41OTZ6IiBmaWxsPSIjMzg1OEU5Ii8+PC9zdmc+Cg==); + } + } + + &.callout-alert { + --wp--custom--wporg-callout--color--background: var( + --wp--preset--color--lemon-3 + ); + + &:before { + background-image: url(data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMjQiIGhlaWdodD0iMjQiIGZpbGw9Im5vbmUiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyI+PHBhdGggZmlsbC1ydWxlPSJldmVub2RkIiBjbGlwLXJ1bGU9ImV2ZW5vZGQiIGQ9Ik0xOS42IDEyYTcuNiA3LjYgMCAxIDEtMTUuMiAwIDcuNiA3LjYgMCAwIDEgMTUuMiAwem0xLjQgMGE5IDkgMCAxIDEtMTggMCA5IDkgMCAwIDEgMTggMHptLTguMzIxIDIuMDkzbC4xMjgtNy4xNzdoLTEuNjE5bC4xMjggNy4xNzdoMS4zNjN6bS0xLjM3NyAyLjcwNWEuOTYuOTYgMCAwIDAgLjY5OC4yODYuOTMuOTMgMCAwIDAgLjQ4Ny0uMTMzIDEuMDE3IDEuMDE3IDAgMCAwIC40OTctLjg1MS45NDguOTQ4IDAgMCAwLS4yOTUtLjY4OS45NC45NCAwIDAgMC0uNjg5LS4yOS45NTIuOTUyIDAgMCAwLS42OTguMjkuOTE0LjkxNCAwIDAgMC0uMjg2LjY4OS45MzUuOTM1IDAgMCAwIC4yODYuNjk4eiIgZmlsbD0iI0I3QjM1QiIvPjwvc3ZnPgo=); + } + } + + &.callout-warning { + --wp--custom--wporg-callout--color--background: var( + --wp--preset--color--pomegrade-3 + ); + + &:before { + background-image: url(data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMjQiIGhlaWdodD0iMjQiIGZpbGw9Im5vbmUiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyI+PG1hc2sgaWQ9ImEiIGZpbGw9IiNmZmYiPjxwYXRoIGQ9Ik0yMC41NDMgMTJhOSA5IDAgMSAxLTE4IDAgOSA5IDAgMCAxIDE4IDB6Ii8+PC9tYXNrPjxwYXRoIGQ9Ik0xOS4xNDIgMTJhNy42IDcuNiAwIDAgMS03LjYgNy42djIuOGM1Ljc0NCAwIDEwLjQtNC42NTYgMTAuNC0xMC40aC0yLjh6bS03LjYgNy42YTcuNiA3LjYgMCAwIDEtNy42LTcuNmgtMi44YzAgNS43NDQgNC42NTcgMTAuNCAxMC40IDEwLjR2LTIuOHptLTcuNi03LjZhNy42IDcuNiAwIDAgMSA3LjYtNy42VjEuNkM1LjggMS42IDEuMTQzIDYuMjU2IDEuMTQzIDEyaDIuOHptNy42LTcuNmE3LjYgNy42IDAgMCAxIDcuNiA3LjZoMi44YzAtNS43NDQtNC42NTYtMTAuNC0xMC40LTEwLjR2Mi44eiIgZmlsbD0iI0UyNkY1NiIgbWFzaz0idXJsKCNhKSIvPjxwYXRoIGZpbGw9IiNFMjZGNTYiIGQ9Ik0xNS41NzMgMTUuMDRsLS45OS45OS03LjA3MS03LjA3Ljk5LS45OXoiLz48cGF0aCBmaWxsPSIjRTI2RjU2IiBkPSJNMTQuNTg0IDcuOTdsLjk5Ljk5LTcuMDcgNy4wNy0uOTktLjk5eiIvPjwvc3ZnPgo=); + } + } + + [data-theme='dark'] & { + --wp--custom--wporg-callout--color--text: #e6e6e6; + } +} From f8530758f3d35d96085c3b707ad6efe864824a7d Mon Sep 17 00:00:00 2001 From: Fellyph Cintra Date: Wed, 15 Apr 2026 12:04:51 +0100 Subject: [PATCH 02/12] replace info component on blueprint pages --- packages/docs/site/docs/blueprints/04-resources.md | 6 ++++-- .../docs/site/docs/blueprints/05-steps-shorthands.md | 10 ++++++---- .../docs/blueprints/07-json-api-and-function-api.md | 7 +++++-- .../blueprints/09-troubleshoot-and-debug-blueprints.md | 6 ++++-- 4 files changed, 19 insertions(+), 10 deletions(-) diff --git a/packages/docs/site/docs/blueprints/04-resources.md b/packages/docs/site/docs/blueprints/04-resources.md index 5959544037b..bcd9279ff30 100644 --- a/packages/docs/site/docs/blueprints/04-resources.md +++ b/packages/docs/site/docs/blueprints/04-resources.md @@ -7,11 +7,13 @@ description: A technical reference for "Resource References." Learn how to use e "Resource References" allow you use external files in Blueprints -:::info +
+ Blueprints steps such as [`installPlugin`](/blueprints/steps#InstallPluginStep) or [`installTheme`](/blueprints/steps#InstallThemeStep) require a location of the plugin or theme to be installed. That location can be defined as [a `URL` resource](#urlreference) of the `.zip` file containing the theme or plugin. It can also be defined as a [`wordpress.org/plugins`](#corepluginreference) or [`wordpress.org/themes`](#corethemereference) resource for those plugins/themes published in the official WordPress directories. -::: + +
The following resource references are available: diff --git a/packages/docs/site/docs/blueprints/05-steps-shorthands.md b/packages/docs/site/docs/blueprints/05-steps-shorthands.md index 69770db7545..fbf9bf8dd6c 100644 --- a/packages/docs/site/docs/blueprints/05-steps-shorthands.md +++ b/packages/docs/site/docs/blueprints/05-steps-shorthands.md @@ -122,9 +122,11 @@ Or The `shorthand` syntax and the `step` syntax correspond to each other. Every `step` specified with the `shorthand` syntax is added to the top of the `steps` array in arbitrary order. -:::info **Which should you choose?** +
-- Use `shorthands` when **brevity** is your main concern. -- Use explicit `steps` when you need more control over the **execution order**. +**Which should you choose?** -::: +- Use `shorthands` when **brevity** is your main concern. +- Use explicit `steps` when you need more control over the **execution order**. + +
diff --git a/packages/docs/site/docs/blueprints/07-json-api-and-function-api.md b/packages/docs/site/docs/blueprints/07-json-api-and-function-api.md index e59a3237346..fa7ab0bffa1 100644 --- a/packages/docs/site/docs/blueprints/07-json-api-and-function-api.md +++ b/packages/docs/site/docs/blueprints/07-json-api-and-function-api.md @@ -12,12 +12,15 @@ JSON is merely a wrapper around the functions. Whether you use the JSON steps or You can use Blueprints both with the web and the node.js versions of WordPress Playground. -:::info Blueprints version 2 +
+ +**Blueprints version 2** The team is exploring ways to transition Blueprints from a TypeScript library to a PHP library. This would allow people to run Blueprints in any WordPress environments: Playground, a hosted site, or a local setup. The proposed [new specification](https://github.com/WordPress/blueprints-library/issues/6) is discussed on a separate [GitHub repository](https://github.com/WordPress/blueprints-library/), and you’re more than welcome to join (there or on the [#playground](https://wordpress.slack.com/archives/C04EWKGDJ0K) Slack channel) and help shape the next generation of Playground. -::: + +
## Differences between JSON and Function APIs diff --git a/packages/docs/site/docs/blueprints/09-troubleshoot-and-debug-blueprints.md b/packages/docs/site/docs/blueprints/09-troubleshoot-and-debug-blueprints.md index 21b0ab66764..dd7e7433f18 100644 --- a/packages/docs/site/docs/blueprints/09-troubleshoot-and-debug-blueprints.md +++ b/packages/docs/site/docs/blueprints/09-troubleshoot-and-debug-blueprints.md @@ -93,9 +93,11 @@ You can `error_log` your own error messages through [`runPHP` step](/blueprints/ ![Log errors snapshot](https://raw.githubusercontent.com/WordPress/wordpress-playground/refs/heads/trunk/packages/docs/site/static/img/blueprints/log-errors.webp) -:::info +
+ When you download your Playground instance as a `zip` through the ["Download as zip" option](/web-instance#playground-options-menu) you'll also download the `debug.log` file containing all the logs from your Playground instance. -::: + +
## Ask for help From b373d3cdcfb85c5c46b29bdef40be208078f064c Mon Sep 17 00:00:00 2001 From: Fellyph Cintra Date: Wed, 15 Apr 2026 12:05:18 +0100 Subject: [PATCH 03/12] replace info component on developer pages --- .../developers/05-local-development/01-wp-now.md | 12 +++++++----- .../05-local-development/02-vscode-extension.md | 6 ++++-- .../05-local-development/04-wp-playground-cli.md | 12 ++++++++---- .../site/docs/developers/06-apis/01-index.md | 16 ++++++++++------ .../06-apis/javascript-api/01-index.md | 12 ++++++++---- .../developers/06-apis/query-api/01-index.md | 6 ++++-- .../developers/07-xdebug/02-getting-started.md | 12 ++++++++---- .../10-browser-iframe-rendering.md | 12 ++++++++---- .../18-host-your-own-playground.md | 6 ++++-- 9 files changed, 61 insertions(+), 33 deletions(-) diff --git a/packages/docs/site/docs/developers/05-local-development/01-wp-now.md b/packages/docs/site/docs/developers/05-local-development/01-wp-now.md index 39da7ee495e..0b3dcf0f784 100644 --- a/packages/docs/site/docs/developers/05-local-development/01-wp-now.md +++ b/packages/docs/site/docs/developers/05-local-development/01-wp-now.md @@ -14,17 +14,19 @@ The NPM package @wp-now/wp-now is deprecated and won't receive updates in the fu Key Features: -- **Command-line Interface**: Easy to use for developers comfortable with CLI. -- **Quick Setup**: Set up a local WordPress environment in seconds. -- **Customizable**: Allows for configuration to suit specific development needs. +- **Command-line Interface**: Easy to use for developers comfortable with CLI. +- **Quick Setup**: Set up a local WordPress environment in seconds. +- **Customizable**: Allows for configuration to suit specific development needs. [`@wp-now/wp-now`](https://www.npmjs.com/package/@wp-now/wp-now) is a CLI tool to spin up a WordPress site with a single command. Similarly to the [VS Code extension](/developers/local-development/vscode-extension), it uses a portable WebAssembly version of PHP and SQLite. No Docker, MySQL, or Apache are required. -:::info **Documentation** +
+ +**Documentation** `wp-now` is maintained in a different GitHub repository, [Playground Tools](https://github.com/WordPress/playground-tools/). You can find the latest documentation in the [dedicated README file](https://github.com/WordPress/playground-tools/blob/trunk/packages/wp-now/README.md). -::: +
## Launch wp-now in a plugin or theme directory diff --git a/packages/docs/site/docs/developers/05-local-development/02-vscode-extension.md b/packages/docs/site/docs/developers/05-local-development/02-vscode-extension.md index fed6024ea98..9c1786cef21 100644 --- a/packages/docs/site/docs/developers/05-local-development/02-vscode-extension.md +++ b/packages/docs/site/docs/developers/05-local-development/02-vscode-extension.md @@ -11,11 +11,13 @@ Key Features: - **Integrated Development**: Develop WordPress sites directly within VS Code. - **Ease of Use**: Simplifies the development workflow with integrated tools. -:::info **Documentation** +
+ +**Documentation** The VS Code extension is maintained in a different GitHub repository, [Playground Tools](https://github.com/WordPress/playground-tools/). You can find the latest documentation in the [dedicated README file](https://github.com/WordPress/playground-tools/blob/trunk/packages/vscode-extension/README.md). -::: +
## Installation and Usage: diff --git a/packages/docs/site/docs/developers/05-local-development/04-wp-playground-cli.md b/packages/docs/site/docs/developers/05-local-development/04-wp-playground-cli.md index f54c9708d3a..ef257295380 100644 --- a/packages/docs/site/docs/developers/05-local-development/04-wp-playground-cli.md +++ b/packages/docs/site/docs/developers/05-local-development/04-wp-playground-cli.md @@ -66,9 +66,11 @@ This is useful when: - Testing fresh installation scenarios - Your site data became corrupted or inconsistent -:::info +
+ The `--reset` flag works only with `start`. For `server`, manually delete the persisted site directory at `~/.wordpress-playground/sites//`. -::: + +
### Choosing a WordPress and PHP Version @@ -119,9 +121,11 @@ Consider mounting your WordPress project files before the WordPress installation npx @wp-playground/cli@latest server --mount-before-install=.:/wordpress/ ``` -:::info +
+ On Windows, the path format `/host/path:/vfs/path` can cause issues. To resolve this, use the flags `--mount-dir` and `--mount-dir-before-install`. These flags let you specify host and virtual file system paths in an alternative format: `"/host/path"` `"/vfs/path"`. -::: + +
### Understanding Data Persistence and SQLite Location in `server` mode diff --git a/packages/docs/site/docs/developers/06-apis/01-index.md b/packages/docs/site/docs/developers/06-apis/01-index.md index fcaadafd02e..6e9e5466a52 100644 --- a/packages/docs/site/docs/developers/06-apis/01-index.md +++ b/packages/docs/site/docs/developers/06-apis/01-index.md @@ -27,9 +27,11 @@ This is called [Query API](/developers/apis/query-api/) and you can learn more a ``` -:::info +
+ Check the [Query API](/developers/apis/query-api) section for more info. -::: + +
### Blueprints @@ -85,11 +87,11 @@ wp_insert_post(array(

-:::info +
Blueprints play a significant role in WordPress Playground, so they have their own dedicated documentation hub. Learn more about JSON Blueprints at the [Blueprints Docs Hub](/blueprints). -::: +
### JavaScript API @@ -110,9 +112,11 @@ The `@wp-playground/client` package provides a JavaScript API you can use to ful ``` -:::info +
+ Check the [JavaScript API](/developers/apis/javascript-api/) section for more info. -::: + +
## Playground APIs Concepts diff --git a/packages/docs/site/docs/developers/06-apis/javascript-api/01-index.md b/packages/docs/site/docs/developers/06-apis/javascript-api/01-index.md index 7b0b6c9834a..4313e2be8f4 100644 --- a/packages/docs/site/docs/developers/06-apis/javascript-api/01-index.md +++ b/packages/docs/site/docs/developers/06-apis/javascript-api/01-index.md @@ -6,13 +6,15 @@ slug: /developers/apis/javascript-api WordPress Playground comes with a JavaScript API client that grants you full control over your WordPress. -:::info API here doesn't mean "REST API" +
+ +**API here doesn't mean "REST API"** WordPress Playground is a browser-based application. The term API here refers to a set of functions you can call inside JavaScript. This is **not** a network-based REST API. -::: +
## Quick start @@ -38,12 +40,14 @@ Here's the shortest example of how to use the JavaScript API in a HTML page: ``` -:::info /remote.html is a special URL +
+ +**/remote.html is a special URL** `/remote.html` is a special URL that loads the Playground API endpoint instead of the demo app with the browser UI. Read more about the difference between `/` and `/remote.html` and [on this page](/developers/apis/javascript-api/-html-vs-remote-html). -::: +
## Controlling the website diff --git a/packages/docs/site/docs/developers/06-apis/query-api/01-index.md b/packages/docs/site/docs/developers/06-apis/query-api/01-index.md index a6552000645..0a2138a5747 100644 --- a/packages/docs/site/docs/developers/06-apis/query-api/01-index.md +++ b/packages/docs/site/docs/developers/06-apis/query-api/01-index.md @@ -54,11 +54,13 @@ For example, the following code embeds a Playground with a preinstalled Gutenber ``` -:::info CORS policy +
+ +**CORS policy** To import files from a URL, such as a site zip package, they must be served with `Access-Control-Allow-Origin` header set. For reference, see: [Cross-Origin Resource Sharing (CORS)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS#the_http_response_headers). -::: +
## GitHub Export Options diff --git a/packages/docs/site/docs/developers/07-xdebug/02-getting-started.md b/packages/docs/site/docs/developers/07-xdebug/02-getting-started.md index a363bb6d9d1..87ee25d7204 100644 --- a/packages/docs/site/docs/developers/07-xdebug/02-getting-started.md +++ b/packages/docs/site/docs/developers/07-xdebug/02-getting-started.md @@ -27,17 +27,21 @@ npx @wp-playground/cli@latest server --xdebug This starts WordPress on `http://127.0.0.1:9400` with Xdebug enabled. Now you can connect a debugger. -:::info +
+ Only one project can be debugged at a time. -::: + +
## Starting with IDE integration Similar to the process with DevTools, let's use the same plugin code from before to debug with VS Code, and add the `--experimental-unsafe-ide-integration=vscode` flag. This flag will optimize the setup process for VS Code. If you're working with PhpStorm, add the `--experimental-unsafe-ide-integration=phpstorm` flag. -:::info +
+ This flag is marked as `unsafe` because it edits the IDE config files to set Xdebug path mappings and web server details. **CAUTION:** If there are bugs, this feature may cause your IDE configuration files to break. Please consider backing up your IDE configs before using this feature. -::: + +
To debug in VS Code, you'll need the following prerequisites: diff --git a/packages/docs/site/docs/developers/23-architecture/10-browser-iframe-rendering.md b/packages/docs/site/docs/developers/23-architecture/10-browser-iframe-rendering.md index 474ab33e696..9fc38ebe88e 100644 --- a/packages/docs/site/docs/developers/23-architecture/10-browser-iframe-rendering.md +++ b/packages/docs/site/docs/developers/23-architecture/10-browser-iframe-rendering.md @@ -22,15 +22,19 @@ Now, consider an iframe with the same link in it: This time, click the link in the browser to load `page.php` **inside the iframe**. The top-level `index.html`, where the PHP application runs, remains unaffected. That's why iframes are crucial for the `@php-wasm/web` setup. -:::info Crash reports +
+ +**Crash reports** + Playground doesn't collect crash reports automatically. Instead, it prompts users to submit a crash report when an instance fails to run in the browser. The report includes a log, description, and a URL, and users can modify it before submitting it. The [Logger API](https://github.com/WordPress/wordpress-playground/blob/trunk/packages/playground/website/public/logger.php) handles it from there. This simple REST API validates the data and sends it to the **Making WordPress** [#playground-logs Slack channel](https://wordpress.slack.com/archives/C06Q5DCKZ3L). -::: + +
## Iframes caveats -- `target="_top"` isn't handled yet, so clicking links with `target="_top"` will reload the page you’re working on. -- JavaScript popups originating in the `iframe` may not always display. +- `target="_top"` isn't handled yet, so clicking links with `target="_top"` will reload the page you’re working on. +- JavaScript popups originating in the `iframe` may not always display. diff --git a/packages/docs/site/docs/developers/23-architecture/18-host-your-own-playground.md b/packages/docs/site/docs/developers/23-architecture/18-host-your-own-playground.md index 6520539fdbd..768b31f1b5c 100644 --- a/packages/docs/site/docs/developers/23-architecture/18-host-your-own-playground.md +++ b/packages/docs/site/docs/developers/23-architecture/18-host-your-own-playground.md @@ -137,11 +137,13 @@ For these to work, you need a server environment with Apache and PHP installed. As an alternative to Apache, here is an example of using NGINX to serve the Playground. -:::info Refer to the source file +
+ +**Refer to the source file** The example may be outdated. Please check [the source file](https://github.com/WordPress/wordpress-playground/blob/trunk/packages/playground/remote/.htaccess) for the latest version. -::: +
The combined Apache `.htaccess` file looks like this. From a38fc7e6f152a67841b91c85956ed6ffef4ed5a8 Mon Sep 17 00:00:00 2001 From: Fellyph Cintra Date: Wed, 15 Apr 2026 12:05:48 +0100 Subject: [PATCH 04/12] replace info component on main pages --- packages/docs/site/docs/main/about/build.md | 4 +- packages/docs/site/docs/main/about/launch.md | 6 +- .../docs/site/docs/main/contributing/code.md | 24 +- .../docs/main/contributing/contributor-day.md | 18 +- .../docs/main/contributing/translations.md | 24 +- .../guides/e2e-testing-with-playwright.md | 480 +++++++++--------- .../docs/main/guides/for-plugin-developers.md | 22 +- .../docs/main/guides/for-theme-developers.md | 14 +- .../main/guides/playground-for-everyone.md | 8 +- .../guides/providing-content-for-your-demo.md | 5 +- packages/docs/site/docs/main/intro.md | 6 +- .../docs/site/docs/main/quick-start-guide.md | 18 +- 12 files changed, 329 insertions(+), 300 deletions(-) diff --git a/packages/docs/site/docs/main/about/build.md b/packages/docs/site/docs/main/about/build.md index adf50fb1ee0..2cdac025df2 100644 --- a/packages/docs/site/docs/main/about/build.md +++ b/packages/docs/site/docs/main/about/build.md @@ -36,11 +36,11 @@ With Google Chrome you can synchronize your Playground instance with a local dir - An empty directory – to save this Playground and start syncing - An existing directory – to load it here and start syncing -:::info +
This feature is only available for Google Chrome for now. It won't work with other browsers yet. -::: +
Regarding changes done on both sides of the connection: diff --git a/packages/docs/site/docs/main/about/launch.md b/packages/docs/site/docs/main/about/launch.md index f5d54d3c32c..8940ffe83fa 100644 --- a/packages/docs/site/docs/main/about/launch.md +++ b/packages/docs/site/docs/main/about/launch.md @@ -30,9 +30,11 @@ This [WordPress Playground block](https://wordpress.org/plugins/interactive-code With this block you have a straightforward and effective way to create live WordPress environments that can be embedded within your blog posts. -:::info +
+ For any issues or questions about the WordPress Playground Block, please open a GitHub issue in the [playground-tools](https://github.com/WordPress/playground-tools) repository. -::: + +
## Put a native app running WordPress in the App Store. diff --git a/packages/docs/site/docs/main/contributing/code.md b/packages/docs/site/docs/main/contributing/code.md index af2524088f6..35cde6637c2 100644 --- a/packages/docs/site/docs/main/contributing/code.md +++ b/packages/docs/site/docs/main/contributing/code.md @@ -8,20 +8,22 @@ description: A guide for code contributions, covering how to fork the repo, set Like all WordPress projects, Playground uses GitHub to manage code and track issues. The main repository is at [https://github.com/WordPress/wordpress-playground](https://github.com/WordPress/wordpress-playground) and the Playground Tools repository is at [https://github.com/WordPress/playground-tools/](https://github.com/WordPress/playground-tools/). -:::info Contribute to Playground Tools +
+ +**Contribute to Playground Tools** This guide includes links to the main repository, but all the steps and options apply for both. If you're interested in the plugins or [local development](/developers/local-development/) tools—start there. -::: +
Browse [the list of open issues](https://github.com/wordpress/wordpress-playground/issues) to find what to work on. The [`Good First Issue`](https://github.com/wordpress/wordpress-playground/issues?q=is%3Aopen+is%3Aissue+label%3A%22Good+First+Issue%22) label is a recommended starting point for first-time contributors. Be sure to review the following resources before you begin: -- [Coding principles](/contributing/coding-standards) -- [Architecture](/developers/architecture) -- [Vision and Philosophy](https://github.com/WordPress/wordpress-playground/issues/472) -- [WordPress Playground Roadmap](https://github.com/WordPress/wordpress-playground/issues/525) +- [Coding principles](/contributing/coding-standards) +- [Architecture](/developers/architecture) +- [Vision and Philosophy](https://github.com/WordPress/wordpress-playground/issues/472) +- [WordPress Playground Roadmap](https://github.com/WordPress/wordpress-playground/issues/525) ## Contribute Pull Requests @@ -67,11 +69,13 @@ Then try `npm run dev` again. This is a common issue on Debian, Ubuntu, and othe When your'e ready, commit the changes and submit a Pull Request. -:::info Formatting +
+ +**Formatting** We handle code formatting and linting automatically. Relax, type away, and let the machines do the work. -::: +
### Running a local Multisite @@ -97,8 +101,8 @@ Your dev server is now available on https://playground.test. If you're using VS Code and have Chrome installed, you can debug Playground in the code editor: -- Open the project folder in VS Code. -- Select Run > Start Debugging from the main menu or press `F5`/`fn`+`F5`. +- Open the project folder in VS Code. +- Select Run > Start Debugging from the main menu or press `F5`/`fn`+`F5`. ### Debugging PHP diff --git a/packages/docs/site/docs/main/contributing/contributor-day.md b/packages/docs/site/docs/main/contributing/contributor-day.md index ca4f527c702..328847f62f1 100644 --- a/packages/docs/site/docs/main/contributing/contributor-day.md +++ b/packages/docs/site/docs/main/contributing/contributor-day.md @@ -18,10 +18,10 @@ We value diverse contributions across various areas, including community buildin This section outlines how you can contribute directly to the WordPress Playground project and its associated tools: -- **Documentation:** Enhance our documentation by improving existing content, developing new guides, or translating materials into different languages. -- **Blueprints:** Create plugin demos for plugins at the WordPress Plugin repository, or develop new Blueprints to enrich our project documentation. -- **Testing the Playground Environment:** Engage in testing the WordPress Playground project itself. You can do this by carefully crafting new issues that describe problems you encounter and suggesting actionable solutions. Test our WordPress web instance (the playground.wordpress.net site), or explore the various applications powered by Playground. Test these tools, observe their functionality, and provide detailed feedback. -- **Product Feedback:** Your insights are invaluable for improving the Playground experience. This includes general feedback on the web instance, the application, and any server-side tools. +- **Documentation:** Enhance our documentation by improving existing content, developing new guides, or translating materials into different languages. +- **Blueprints:** Create plugin demos for plugins at the WordPress Plugin repository, or develop new Blueprints to enrich our project documentation. +- **Testing the Playground Environment:** Engage in testing the WordPress Playground project itself. You can do this by carefully crafting new issues that describe problems you encounter and suggesting actionable solutions. Test our WordPress web instance (the playground.wordpress.net site), or explore the various applications powered by Playground. Test these tools, observe their functionality, and provide detailed feedback. +- **Product Feedback:** Your insights are invaluable for improving the Playground experience. This includes general feedback on the web instance, the application, and any server-side tools. All feedback, including reported issues and test results, can be submitted through our GitHub repository. @@ -84,11 +84,11 @@ npm install npm run dev ``` -:::info +
If you’re unsure about the steps listed above, visit the official [Gutenberg Project Contributor Guide](https://developer.wordpress.org/block-editor/contributors/). Note that in this case, `@wp-playground/cli` replaces `wp-env`. -::: +
Open a new terminal terminal tab, navigate to the Gutenberg directory, and start WordPress using `@wp-playground/cli`: @@ -133,6 +133,6 @@ You can translate supported WordPress Plugins by loading the plugin you want to Have a question or an idea for a new feature? Found a bug? Something’s not working as expected? We’re here to help: -- During Contributor Day, you can reach us at the **Playground table**. -- Open an issue on the [WordPress Playground GitHub repository](https://github.com/WordPress/wordpress-playground/issues/new). If your focus is the VS Code extension, NPM package, or the plugins, open an issue on the [Playground Tools repository](https://github.com/WordPress/playground-tools/issues/new). -- Share your feedback on the [**#playground** Slack channel](https://wordpress.slack.com/archives/C04EWKGDJ0K). +- During Contributor Day, you can reach us at the **Playground table**. +- Open an issue on the [WordPress Playground GitHub repository](https://github.com/WordPress/wordpress-playground/issues/new). If your focus is the VS Code extension, NPM package, or the plugins, open an issue on the [Playground Tools repository](https://github.com/WordPress/playground-tools/issues/new). +- Share your feedback on the [**#playground** Slack channel](https://wordpress.slack.com/archives/C04EWKGDJ0K). diff --git a/packages/docs/site/docs/main/contributing/translations.md b/packages/docs/site/docs/main/contributing/translations.md index b90662b8c8d..a83772c41ba 100644 --- a/packages/docs/site/docs/main/contributing/translations.md +++ b/packages/docs/site/docs/main/contributing/translations.md @@ -8,17 +8,21 @@ description: Learn how to translate the Playground documentation, including file Help make WordPress Playground accessible to a global audience by translating its documentation. This guide provides everything you need to know to get started. Contributing translations follows the same workflow as any other documentation change. You can either fork the [WordPress/wordpress-playground](https://github.com/WordPress/wordpress-playground) repository and create a pull request (PR) with your changes or edit pages directly using the GitHub UI. -:::info +
+ For a detailed guide on the contribution workflow (forking, creating PRs, etc.), please see our [documentation contribution guide](/contributing/documentation#how-can-i-contribute) -::: + +
## How Translations Work Playground's documentation site is built with Docusaurus, which handles the internationalization (i18n) features. -:::info +
+ To learn more about how Docusaurus manages translations, see the [Internationalization section](https://docusaurus.io/docs/i18n/introduction) of the official Docusaurus documentation. -::: + +
### Configuration @@ -150,9 +154,11 @@ Follow these steps to translate a page: - Describe the pages that you translated - Request a review at `#playground` or `#polyglots` at `wordpress.slack.com` -:::info +
+ We highly recommend submitting pull requests with a small number of translated pages. This approach simplifies the review process and allows for a more gradual and manageable integration of your work. -::: + +
### Translation Tracking Template @@ -336,9 +342,11 @@ Playground is an online tool to experiment and learn about WordPress. This site WordPress Playground é uma ferramenta online onde podes testar e aprender mais sobre o WordPress. Nesta página(Documentação) irá encontrar todas as informações necessárias para começar a trabalhar com o Playground. ``` -:::info +
+ This practice also helps the maintenance team identify outdated translations. When the original English content is updated, we can search the codebase for the old text (now in comments) and flag the corresponding translation for review. -::: + +
To find a reviewer fluent in the language of your PR, you can post a request on the [Make WordPress Polyglots blog](https://make.wordpress.org/polyglots/). Be sure to include the locale tag (e.g., #ja for Japanese) to notify the appropriate General Translation Editors (GTEs). diff --git a/packages/docs/site/docs/main/guides/e2e-testing-with-playwright.md b/packages/docs/site/docs/main/guides/e2e-testing-with-playwright.md index 2bd77dd58e7..f673de1ee40 100644 --- a/packages/docs/site/docs/main/guides/e2e-testing-with-playwright.md +++ b/packages/docs/site/docs/main/guides/e2e-testing-with-playwright.md @@ -7,9 +7,11 @@ sidebar_class_name: navbar-build-item End-to-end testing verifies that your WordPress plugin or theme works correctly from a user's perspective — clicking buttons, filling forms, and navigating pages in a real browser. This guide shows how to combine [Playwright](https://playwright.dev/) with the [WordPress Playground CLI](/developers/local-development/wp-playground-cli) to write reliable E2E tests without Docker, databases, or manual setup. -:::info +
+ This guide assumes familiarity with WordPress plugin or theme development. For an introduction to using Playground in your development workflow, see [WordPress Playground for Plugin Developers](/guides/for-plugin-developers). For Blueprint configuration details, see [Blueprints Getting Started](/blueprints/getting-started). -::: + +
## Prerequisites @@ -36,23 +38,23 @@ This installs Playwright as the test runner, the Playground CLI for creating Wor Create a `playwright.config.ts` file in your project root: ```typescript -import { defineConfig } from "@playwright/test"; +import { defineConfig } from '@playwright/test'; export default defineConfig({ - testDir: "./tests/e2e", - fullyParallel: false, - forbidOnly: !!process.env.CI, - retries: process.env.CI ? 2 : 0, - workers: 1, - reporter: "html", - timeout: 120_000, - expect: { - timeout: 30_000, - }, - use: { - screenshot: "only-on-failure", - trace: "on-first-retry", - }, + testDir: './tests/e2e', + fullyParallel: false, + forbidOnly: !!process.env.CI, + retries: process.env.CI ? 2 : 0, + workers: 1, + reporter: 'html', + timeout: 120_000, + expect: { + timeout: 30_000, + }, + use: { + screenshot: 'only-on-failure', + trace: 'on-first-retry', + }, }); ``` @@ -62,7 +64,7 @@ WordPress Playground needs more time to start than a typical web app. The 120-se By default, Playground will sign the port `9400`. If you want to select a different port, pass `port: [NEW_PORT_NUMBER]` in the `runCLI` options to select a different port: ```typescript -const cli = await runCLI({ command: "server", port: 9500, blueprint }); +const cli = await runCLI({ command: 'server', port: 9500, blueprint }); ``` Then add `baseURL: "http://localhost:9500"` to the `use` section above. Note that `testMatch` defaults to `**/*.spec.ts` — customize it if your test files use a different naming pattern. @@ -77,30 +79,30 @@ The WordPress Playground project uses even longer timeouts (300s test, 60s asser Create `tests/e2e/plugin.spec.ts`: ```typescript -import { test, expect } from "@playwright/test"; -import { runCLI } from "@wp-playground/cli"; +import { test, expect } from '@playwright/test'; +import { runCLI } from '@wp-playground/cli'; let cli: Awaited>; test.beforeAll(async () => { - cli = await runCLI({ - command: "server", - blueprint: { - preferredVersions: { php: "8.3", wp: "latest" }, - login: true, - }, - }); + cli = await runCLI({ + command: 'server', + blueprint: { + preferredVersions: { php: '8.3', wp: 'latest' }, + login: true, + }, + }); }); test.afterAll(async () => { - await cli?.server?.close(); + await cli?.server?.close(); }); -test("WordPress dashboard loads", async ({ page }) => { - await page.goto(`${cli.serverUrl}/wp-admin/`); - // WordPress core admin elements lack ARIA roles — CSS selectors are acceptable here - await expect(page.locator("#wpbody-content")).toBeVisible(); - await expect(page).toHaveTitle(/Dashboard/); +test('WordPress dashboard loads', async ({ page }) => { + await page.goto(`${cli.serverUrl}/wp-admin/`); + // WordPress core admin elements lack ARIA roles — CSS selectors are acceptable here + await expect(page.locator('#wpbody-content')).toBeVisible(); + await expect(page).toHaveTitle(/Dashboard/); }); ``` @@ -134,13 +136,13 @@ In the WordPress admin, some core elements (admin bar, meta boxes) rely on IDs a ```typescript // ✅ Preferred: semantic locator (works because WP renders a real