` instead of an `
```
-This time, clicking the link the browser to load `page.php` **inside the iframe**. The top-level index.html where the PHP application runs remains unaffected. This is why iframes are a crucial part of the `@php-wasm/web` setup.
+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
+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. This means that clicking on `
Click here` will reload the main browser tab.
-- JavaScript popup windows originating in the iframe may not work correctly yet.
+- `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/11-architecture/15-wordpress.md b/packages/docs/site/docs/11-architecture/15-wordpress.md
index 1e00265c5b..7646354f0a 100644
--- a/packages/docs/site/docs/11-architecture/15-wordpress.md
+++ b/packages/docs/site/docs/11-architecture/15-wordpress.md
@@ -1,14 +1,10 @@
----
-title: WordPress support
----
-
# WordPress support
WordPress, as a PHP application, can run on PHP WebAssembly. However, there are a few caveats.
## SQLite
-First, WordPress requires MySQL. However, there isn't a WebAssembly version of MySQL you could run in the browser. WordPress Playground therefore ships PHP with the [native SQLite driver](https://www.php.net/manual/en/ref.pdo-sqlite.php) and leans on SQLite.
+First, WordPress requires MySQL. However, there isn't a WebAssembly version of MySQL you could run in the browser. WordPress Playground, therefore, ships PHP with the [native SQLite driver](https://www.php.net/manual/en/ref.pdo-sqlite.php) and leans on SQLite.
But how can WordPress run on a different database?
@@ -16,7 +12,7 @@ Behind the scenes, the official [SQLite Database Integration](https://github.com
## WordPress in the browser
-WordPress Playground ships a [bundled WordPress](./06-wasm-php-data-dependencies.md) that you can use in the browser. It's optimized for size and the installation wizard is already completed for you.
+WordPress Playground ships a [bundled WordPress](./06-wasm-php-data-dependencies.md) that you can use in the browser. It's optimized for size, and the installation wizard is run for you.
## WordPress in Node.js
diff --git a/packages/docs/site/docs/11-architecture/18-host-your-own-playground.md b/packages/docs/site/docs/11-architecture/18-host-your-own-playground.md
index 2dd5614dd7..8439bdb4b9 100644
--- a/packages/docs/site/docs/11-architecture/18-host-your-own-playground.md
+++ b/packages/docs/site/docs/11-architecture/18-host-your-own-playground.md
@@ -58,6 +58,7 @@ git clone -b trunk --single-branch --depth 1 git@github.com:WordPress/wordpress-
```
Enter the `wordpress-playground` directory.
+
```sh
cd wordpress-playground
```
@@ -98,11 +99,9 @@ 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 source files
-
-This example may go out of date. It is recommended to refer to the source files.
+:::info Refer to the source file
-- [packages/playground/wordpress/public/.htaccess](https://github.com/WordPress/wordpress-playground/blob/trunk/packages/playground/wordpress/public/.htaccess)
+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.
:::
diff --git a/packages/docs/site/docs/12-limitations/01-index.md b/packages/docs/site/docs/12-limitations/01-index.md
index 7106455620..d17d7fb74a 100644
--- a/packages/docs/site/docs/12-limitations/01-index.md
+++ b/packages/docs/site/docs/12-limitations/01-index.md
@@ -1,36 +1,41 @@
---
-title: Limitations
slug: /limitations
---
# Limitations
-WordPress Playground has a few limitations that you should be aware of.
+WordPress Playground is under active development and has some limitations you should keep in mind when running it and developing with it.
-## If you are a user
+You can track the status of these issues on the [Playground Project board](https://github.com/orgs/WordPress/projects/180).
-import Limitations from '@site/docs/\_fragments/\_limitations_ui.md';
+## In the browser
-
+### Access the Plugins, Themes, Blocks, or Patterns directories
-## If you are a developer
+Playground [disables network connections](../09-blueprints-api/03-data-format.md#features) by default, blocking access to wp.org assets (themes, plugins, blocks, or patterns) in `wp-admin`. You can still upload zipped plugin and theme files from your device or enable the option via the [Query API](../08-query-api/01-index.md#available-options) or [Blueprints API](../09-blueprints-api/09-troubleshoot-and-debug-blueprints.md#review-common-gotchas).
-### Iframe quirks
+### Temporary by design
-WordPress is rendered in an iframe, which makes it hard to correctly handle `target="_top"` in links. This means that clicking on `
Click here` may reload the main browser tab.
+As Playground [streams rather than serves](../01-start-here/02-overview.md#streamed-not-served) WordPress, all database changes and uploads will be gone when you refresh the page. To avoid losing your work, either [export your work](../02-start-using/01-index.md#save-your-site) before or enable storage in the browser/device via the [Query API](../08-query-api/01-index.md#available-options) or the UI.
-Also, JavaScript popup windows originating in the iframe may not be displayed in certain cases.
+## When developing with Playground
-### Pthreads Support
+### Iframe quirks
-The WebAssembly version of PHP is built without pthreads support, which means you cannot use `pcntl_` functions like `pcntl_fork()` or `pcntl_exec()`. Most of the time, you don't need them, but there are a few WP-CLI commands and a few corner-cases in PHPUnit tests that use them.
+Playground renders WordPress in an `iframe` so clicking links with `target="_top"` will reload the page you’re working on.
+Also, JavaScript popups originating in the `iframe` may not always display.
-You can track the progress of adding pthreads support at https://github.com/WordPress/wordpress-playground/issues/347.
+### Run WordPress PHP functions
-### XDebug Support
+Playground supports running PHP code in Blueprints using the [`runPHP` step](../09-blueprints-api/05-steps.md#RunPHPStep). To run WordPress-specific PHP functions, you’d need to first require [wp-load.php](https://github.com/WordPress/WordPress/blob/master/wp-load.php):
-XDebug is not supported in the WebAssembly version of PHP. You can track the progress of adding XDebug support at https://github.com/WordPress/wordpress-playground/issues/314.
+```json
+{
+ "step": "runPHP",
+ "code": ""
+}
+```
-### Fibers
+### Using WP-CLI
-Fibers are a PHP 8.1+ feature that is currently unsupported in Playground. See https://github.com/WordPress/wordpress-playground/blob/9065025043209ce06c9540886567ca5bc0ccfb11/packages/php-wasm/compile/Dockerfile#L484-L493 for more information.
+You can execute `wp-cli` commands via the Blueprints [`wp-cli`](../09-blueprints-api/05-steps.md#WPCLIStep) step. However, since Playground runs in the browser, it doesn't support the [full array](https://developer.wordpress.org/cli/commands/) of available commands. While there is no definite list of supported commands, experimenting in [the online demo](https://playground.wordpress.net/demos/wp-cli.html) will help you assess what's possible.
diff --git a/packages/docs/site/docs/13-contributing/01-index.md b/packages/docs/site/docs/13-contributing/01-index.md
index b0a3a0076d..ae7aeb6af2 100644
--- a/packages/docs/site/docs/13-contributing/01-index.md
+++ b/packages/docs/site/docs/13-contributing/01-index.md
@@ -1,21 +1,25 @@
----
-title: Start Contributing
----
+# Start contributing
-# Start Contributing
-
-WordPress Playground is an open-source project and welcomes all contributors from code to design, and from documentation to triage. Don't worry, you don't need to know WebAssembly to contribute!
+WordPress Playground is an open-source project that welcomes all contributors—from code to design, documentation to triage.
## How can I contribute?
- Code? See the [developer section](./02-code.md).
- Documentation? See the [documentation section](./20-documentation.md).
-- Reporting bugs? Open an [issue](https://github.com/WordPress/wordpress-playground/issues/new) in the repository.
-- Triage – see the [triage section](./05-triage.md).
-- Ideas, designs or anything else? Open a [GitHub discussion](https://github.com/WordPress/wordpress-playground/discussions) and let's talk!
+- Reporting bugs? Open a [new issue](https://github.com/WordPress/wordpress-playground/issues/new) in the main GitHub repository, or in [Playground Tools](https://github.com/WordPress/playground-tools/issues/new).
+- Ideas, designs, or anything else? Open a [GitHub discussion](https://github.com/WordPress/wordpress-playground/discussions), and let's talk!
## Guidelines
-- As with all WordPress projects, we want to ensure a welcoming environment for everyone. With that in mind, all contributors are expected to follow our [Code of Conduct](https://make.wordpress.org/handbook/community-code-of-conduct/).
-- Contributors should review the [coding standards](./03-coding-standards.md).
-- You maintain copyright over any contribution you make. By submitting a pull request you agree to release that code under [WordPress Playground License](https://github.com/WordPress/wordpress-playground/blob/HEAD/LICENSE).
+- As with all WordPress projects, we want to ensure a welcoming and respectful environment for everyone. Please read our community's [Code of Conduct](https://make.wordpress.org/handbook/community-code-of-conduct/) to learn more.
+- Code contributors should review the [coding principles](./03-coding-standards.md).
+- You maintain copyright over any contribution you make. By submitting a Pull Request, you agree to release that code under [WordPress Playground License](https://github.com/WordPress/wordpress-playground?tab=GPL-2.0-1-ov-file#readme).
+
+# Triaging issues
+
+Want to help sort through open issues and resolve potential bugs? Here's how:
+
+1. Review the [list of open issues](https://github.com/WordPress/wordpress-playground/issues?q=is%3Aopen+is%3Aissue) and find the ones that you can help with. Same goes for the [Plaground Tools repository](https://github.com/WordPress/playground-tools/issues?q=is%3Aopen+is%3Aissue).
+2. Read through the description and comments.
+3. If it's a bug you can reproduce, add a descriptive comment or a potential fix.
+4. Otherwise, add a comment with any additional information that may be helpful.
diff --git a/packages/docs/site/docs/13-contributing/02-code.md b/packages/docs/site/docs/13-contributing/02-code.md
index ef13d96fa9..0078efe483 100644
--- a/packages/docs/site/docs/13-contributing/02-code.md
+++ b/packages/docs/site/docs/13-contributing/02-code.md
@@ -1,60 +1,82 @@
---
sidebar_position: 1
-title: Code Contributions
---
-# Code Contributions
+# Code contributions
-The WordPress Playground project uses GitHub for managing code and tracking issues. The main repository is at: [https://github.com/WordPress/wordpress-playground](https://github.com/WordPress/wordpress-playground).
+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/).
-To contribute Pull Requests, you'll need to fork the Playground repository and clone it to your local machine. You can then create a branch, make changes, and submit a pull request.
+:::info Contribute to Playground Tools
-Once you have a fork, you can clone it as follows – just replace `WordPress/wordpress-playground` with your GitHub username and repository name:
+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 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](./03-coding-standards.md)
+- [Architecture](../11-architecture/01-index.md)
+- [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
+
+[Fork the Playground repository](https://github.com/WordPress/wordpress-playground/fork) and clone it to your local machine. To do that, copy and paste these commands into your terminal:
```bash
-git clone -b trunk --single-branch --depth 1 git@github.com:WordPress/wordpress-playground.git
+git clone -b trunk --single-branch --depth 1
+
+# replace `YOUR-GITHUB-USERNAME` with your GitHub username:
+git@github.com:YOUR-GITHUB-USERNAME/wordpress-playground.git
cd wordpress-playground
-nvm use # You'll need Node 16 or later
npm install
+```
+
+Create a branch, make changes, and test it locally by running the following command:
+
+```bash
npm run dev
```
-That's it, WordPress Playground is now running on your machine and you're ready to contribute!
+Playground will open in a new browser tab and refresh automatically with each change.
-Browse [the issues list](https://github.com/wordpress/wordpress-playground/issues) to find issues 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) labels are good starting points.
+When your'e ready, commit the changes and submit a Pull Request.
-Be sure to also review the following resources:
+:::info Formatting
-- [Coding Standards](./03-coding-standards.md)
-- [Packages and projects](./04-packages-and-projects.md)
-- [Vision and Philosophy](https://github.com/WordPress/wordpress-playground/issues/472)
-- [Roadmap](https://github.com/WordPress/wordpress-playground/issues/525)
+We handle code formatting and linting automatically. Relax, type away, and let the machines do the work.
-## HTTPS setup
+:::
-Some Playground features, like multisite, require a local test domain running via HTTPS.
+### Running a local Multisite
-One way to get it set up is with [Laravel Valet](https://laravel.com/docs/10.x/valet).
+WordPress Multisite has a few [restrictions when run locally](https://developer.wordpress.org/advanced-administration/multisite/prepare-network/#restrictions). If you plan to test a Multisite network using Playground's `enableMultisite` step, make sure you either change `wp-now`'s default port or set a local test domain running via HTTPS.
+
+To change `wp-now`'s default port to the one supported by WordPress Multisite, run it using the `--port=80` flag:
+
+```bash
+npx @wp-now/wp-now start --port=80
+```
-Once your Valet is installed, run:
+There are a few ways to set up a local test domain, including editing your `hosts` file. If you're unsure how to do that, we suggest installing [Laravel Valet](https://laravel.com/docs/11.x/valet) and then running the following command:
```bash
valet proxy playground.test http://localhost:5400 --secure
```
-Your dev server is now available via https://playground.test.
+Your dev server is now available on https://playground.test.
## Debugging
-### Debugging with VSCode and Chrome
+### Use VS Code and Chrome
-Playground can be debugged using VSCode and Chrome. To do so, follow these steps:
+If you're using VS Code and have Chrome installed, you can debug Playground in the code editor:
-- Open the project in VSCode
-- Go to the _Run and Debug_ view (Ctrl+Shift+D)
-- Select _Launch Chrome_ from the dropdown
-- Click the green play button to start the debugger (F5)
+- Open the project folder in VS Code.
+- Select Run > Start Debugging from the main menu or press `F5`/`fn`+`F5`.
### Debugging PHP
-In the web version of Playground, you can see PHP errors in the browser console. PHP errors are also logged after every PHP request using `console.debug` in the browser console.
+Playground logs PHP errors in the browser console after every PHP request.
diff --git a/packages/docs/site/docs/13-contributing/03-coding-standards.md b/packages/docs/site/docs/13-contributing/03-coding-standards.md
index 4442765e79..a680fe3aad 100644
--- a/packages/docs/site/docs/13-contributing/03-coding-standards.md
+++ b/packages/docs/site/docs/13-contributing/03-coding-standards.md
@@ -1,73 +1,49 @@
---
sidebar_position: 1
-title: Coding standards
---
-# Coding standards
+# Coding principles
## Error messages
-A good error message tells the reader exactly what to do next. This matters especially for errors thrown by Playground public APIs. Any ambiguity in those prompts the developers to open issues in the repo. However, the error message could provide the reader will all the answers.
+A good error message tells the user what to do next. Any ambiguity in errors thrown by Playground public APIs will prompt the developers to open issues.
-Consider a network error – can we infer what type of error was that and provide a dedicated message outlining the next steps
+Consider a network error, for example—can we infer the type of error and display a relevant message summarizing the next steps?
-- If it's a network error – say your internet connection twitched and reloading the page should fix the issue.
-- If it's 404 – say file couldn't be found.
-- If it's 403 – say it's probably a private resource.
-- If it's a CORS error, provide a paragraph or two of text to explain it's a browser security thing, provide a link that explains what's CORS, say they need to move their file somewhere else, e.g. GitHub / raw.githubusercontent.com, link out to a resource explaining setting up CORS headers on their existing servers.
+- **Network error**: "Your internet connection twitched. Try to reload the page.
+- **404**: "Could not find the file".
+- **403**: "The server blocked access to the file".
+- **CORS**: clarify it's a browser security feature and add a link to a detailed explanation (on MDN or another reliable source). Suggest the user move their file somewhere else, like raw.githubusercontent.com, and link to a resource explaining how to set up CORS headers on their servers.
-## Formatting
-
-Formatting is handled automatically by the relevant tools and verified by CI. Relax, sit back, and let the machines do the work.
+We handle code formatting and linting automatically. Relax, type away, and let the machines do the work.
## Public API
-Playground aims to keep the lowest possible API area.
+Playground aims to keep the narrowest possible API scope.
-Public APIs are easy to add and hard to remove. It only takes one PR to add a new API, but it may take a thousand to remove it – especially if was already consumed in other projects.
+Public APIs are easy to add and hard to remove. It only takes one PR to introduce a new API, but it may take a thousand to remove it, especially if other projects have already consumed it.
-Don't expose anything that is not needed. If you don't need to expose a function, don't. If you don't need to expose a class, don't. If you don't need to expose a constant, don't.
+- Don't expose unnecessary function, class, constant, or other components.
## Blueprints
-Blueprints are the main way to interact with the WordPress Playground. They are JSON files that describe a set of steps to perform. The Playground will execute these steps in order.
-
-### Batteries
-
-Blueprint steps are meant to be small and focused – like Unix tools. They should do one thing and do it well.
-
-When it comes to building new steps:
-
-- It is best not to build it at all
-- If you must build it, try refactoring an existing step first
-- If you cannot do that, make sure the new step opens up an entirely new feature that doesn't do anything that can be achieved with existing steps
-
-### Composability
-
-Blueprint Steps are meant to be composable. This means that you can run them many times over and still get sensible results.
-
-**Don't:**
-
-- Assume your step won't be run more than once.
-- Assume your step will be run in a specific order.
-- Modify PHP files to define constants.
-
-**Do:**
-
-- Add unit tests that run your step multiple times.
-- Store constants in virtual JSON files.
-
-### Ease of use
+Blueprints are the primary way to interact with Playground. These JSON files describe a set of steps that Playground executes in order.
-Blueprints are meant to be easy to use and require the minimal amount of effort on the consumer side.
+### Guidelines
-**Don't:**
+Blueprint steps should be **concise and focused**. They should do one thing and do it well.
-- Require arguments that can be made optional.
-- Require complex arguments when simple ones will do. For example, don't require a plugin path when plugin slug will do.
+- If you need to create a new step, try refactoring an existing one first.
+- If that's not enough, ensure the new step delivers a new capability. Don't replicate the functionality of existing steps.
+- Assume the step would be called more than once.
+- Assume it would run in a specific order.
+- Add unit tests to verify that.
-**Do:**
+Blueprints should be **intuitive and straightforward**.
-- Provide a TypeScript type for the Blueprint. JSON Schema is generated from it.
-- Provide a function to handle a blueprint step. Accept argument of the type you defined in the previous step.
-- Provide usage example in the doc string. It is automatically reflected in the docs.
+- Don't require arguments that can be optional.
+- Use plain argument. For example, `slug` instead of `path`.
+- Define constants in virtual JSON files—don't modify PHP files.
+- Define a TypeScript type for the Blueprint. That's how Playground generates its JSON schema.
+- Write a function to handle a Blueprint step. Accept the argument of the type you defined.
+- Provide a usage example in the doc string. It's automatically reflected in the docs.
diff --git a/packages/docs/site/docs/13-contributing/04-packages-and-projects.md b/packages/docs/site/docs/13-contributing/04-packages-and-projects.md
deleted file mode 100644
index 79d38bc733..0000000000
--- a/packages/docs/site/docs/13-contributing/04-packages-and-projects.md
+++ /dev/null
@@ -1,112 +0,0 @@
----
-sidebar_position: 1
-title: NX – Packages and Projects
----
-
-# NX: Packages and Projects
-
-WordPress Playground uses a tool called [nx](https://nx.dev/) to manage the repository.
-
-Why?
-
-The dependencies between Playground packages [are too complex](https://github.com/WordPress/wordpress-playground/pull/151) to manage with a bundler like webpack. Nx is the right tool for the job. Just look at this dependency graph:
-
-
-
-## Getting started with nx
-
-Start by reviewing the [Nx documentation](https://nx.dev/getting-started/intro). It's a good idea to install the Nx VS Code extension – it makes many common tasks easier.
-
-## Projects
-
-Nx uses the term "project" which is different from an npm "package". A project can be an npm package, a VS Code plugin, a web app that isn't published on npm, or even a directory with nothing more than a Dockerfile and a project.json file.
-
-## Tasks
-
-Every project needs a set of tasks so it can be built, tested, type-checked and so on. Tasks are stored in `project.json` files. Learn more about [tasks in nx documentation](https://nx.dev/core-features/run-tasks).
-
-## Add a new project / package
-
-Nx uses generators to create new packages. There are generators for Node.js libraries, web apps, angular apps, and more.
-
-For example, here's how you can create a new project containing a Node.js app:
-
-```bash
-nx g @nrwl/node:application
-```
-
-Nx will then ask you many questions about the project. For example, it will ask you to choose a build tool. You can answer them in the terminal, or you can use the VS Code extension to answer them in a GUI – the latter is much easier.
-
-### Which tools to choose?
-
-In the Playground repository, we use the following tools:
-
-- TypeScript for type-checking
-- Vite or esbuild for building both web apps and node.js apps
-- Vitest for testing
-
-### After you create a new project
-
-Follow this checklist:
-
-- Add a new `workspaces` in the top-level `package.json` file if needed. Otherwise TypeScript won't work correctly and Lerna won't pick up your package for publishing.
-- Add a `typecheck` task to the `project.json` file in the new project. You can copy it from another project in this repo.
-- Run `nx typecheck
` to make sure TypeScript is set up correctly.
-- If the project needs to ship both ESM and CJS builds, add a `test:esmcjs` task to the `project.json` and add it to the `dependsOn` list of the `test` task. This way the CI will continuously verify whether your double build works. The alternative is to find out when a disappointed extender files an issue.
-- Add the `package-json` task to the build pipeline. See the details below.
-
-### Package.json
-
-Do not add any `dependencies` or `devDependencies` into the `package.json` file of the new project. WordPress Playground keeps track of all dependencies in the top-level `package.json` file and computes the one used by each project automatically using a custom NX executor. The process goes like this:
-
-1. Bundle the project into the `dist` directory, just copy the package.json as is
-2. Add correct dependencies using the `@wp-playground/nx-extensions:package-json` executor
-
-Here's how you should configure the chain of build tasks in your `project.json`:
-
-```json
-{
- "build": {
- "executor": "nx:noop",
- "dependsOn": ["build:package-json"]
- },
- "build:package-json": {
- "executor": "@wp-playground/nx-extensions:package-json",
- "options": {
- "tsConfig": "packages/php-wasm/node/tsconfig.lib.json",
- "outputPath": "dist/packages/php-wasm/node",
- "buildTarget": "php-wasm-node:build:bundle:production"
- },
- "dependsOn": ["build:bundle"]
- },
- "build:bundle": {
- "//": "... your bundle task ..."
- }
-}
-```
-
-## Move a project to a different directory
-
-Use the [@nx/workspace:move](https://nx.dev/packages/workspace/generators/move) generator:
-
-```bash
-nx g @nx/workspace:move --projectName= --destination=
-```
-
-Or use the VS Code extension – again, that's much easier than remembering all the commands.
-
-## Rename a project
-
-Same as above.
-
-## Delete a project
-
-Use the [@nx/workspace:remove](https://nx.dev/packages/workspace/generators/remove) generator:
-
-```bash
-nx g @nx/workspace:remove --projectName=
-```
-
-## Publish a project on npm
-
-See the [publishing](./06-publishing.md) guide.
diff --git a/packages/docs/site/docs/13-contributing/05-triage.md b/packages/docs/site/docs/13-contributing/05-triage.md
deleted file mode 100644
index e32d79e048..0000000000
--- a/packages/docs/site/docs/13-contributing/05-triage.md
+++ /dev/null
@@ -1,15 +0,0 @@
----
-sidebar_position: 1
-title: Triage Contributions
----
-
-# Triaging issues
-
-You may help sort through WordPress Playground issues and determine their priority. Here's how:
-
-1. Go to the [WordPress Playground](https://github.com/WordPress/wordpress-playground/issues) repo on GitHub.
-2. Click on the "Issues" tab to view the list of open issues.
-3. Review the list of issues and look for ones that you can help with.
-4. Once you've found an issue that you want to help with, read through the description and any comments to get a better understanding of the problem.
-5. If you're able to reproduce the issue, add a comment to the issue with steps to reproduce it. This will help the developers to better understand the problem and come up with a solution.
-6. If you're not able to reproduce the issue, add a comment to the issue with any additional information that you think might be helpful. This will help the developers to better understand the problem and come up with a solution.
diff --git a/packages/docs/site/docs/13-contributing/06-publishing.md b/packages/docs/site/docs/13-contributing/06-publishing.md
deleted file mode 100644
index e43cbc9442..0000000000
--- a/packages/docs/site/docs/13-contributing/06-publishing.md
+++ /dev/null
@@ -1,41 +0,0 @@
-# Publishing Packages, Releases, and More
-
-WordPress Playground has many types of artifacts that are published.
-
-NPM packages, GitHub releases, and playground.wordpress.net website are published by project maintainers through GitHub Actions.
-
-Below you'll find more details about parts of that process.
-
-## NPM packages
-
-WordPress Playground is a monorepo and uses Lerna for publishing npm packages.
-
-The publishing process is facilitated by Lerna, and includes automatically incrementing the version number, creating a new tag, and publishing all modified packages to npm simultaneously.
-
-Notably, all published packages share the same version number. All packages use the same version number. If you update a single package, Lerna will automatically bump the version number for all dependent packages.
-
-Each package identifies a distinct organization in its `package.json` file. To publish WordPress Playground packages, you need access to the following npm organizations:
-
-- `@wp-playground`
-- `@php-wasm`
-
-To initiate the publishing process for the all the modified packages, execute the following commands:
-
-```bash
-npm login # this is required only once and it will store the credentials in ~/.npmrc file.
-npm run release
-```
-
-### After publishing
-
-To verify the publishing process went correctly:
-
-1. Please verify https://translate.wordpress.org/projects/wp-plugins/contact-form-7/dev/de/default/playground/ loads as expected. If it doesn't load, something broke.
-
-### When publishing packages goes wrong
-
-Internet connections drop, APIs stop responding, and GitHub rules are nasty. Stuff happens. If the publishing process fails, you may need to bump the version again and force a publish. To do so, execute the following command:
-
-```bash
-npm run release -- --force-publish
-```
diff --git a/packages/docs/site/docs/13-contributing/07-crash-reports.md b/packages/docs/site/docs/13-contributing/07-crash-reports.md
deleted file mode 100644
index 89e8420ea7..0000000000
--- a/packages/docs/site/docs/13-contributing/07-crash-reports.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-sidebar_position: 7
-title: Crash Reports
----
-
-# Playground.WordPress.net Crash Reports
-
-When Playground crashes on Playground.WordPress.net users are able to submit a crash report. These reports are stored in the [#playground-logs channel on the Making WordPress Slack](https://wordpress.slack.com/archives/C06Q5DCKZ3L).
-
-**Playground doesn't collect crash reports automatically.** Instead, users are prompted to submit a crash report when a crash occurs and are able to modify it before submitting. The crash report includes a Playground logs, a description, and the url.
-
-## Development
-
-Logs are sent to the [logger API on Playground.WordPress.net](https://github.com/WordPress/wordpress-playground/blob/c52d7dbd94dbe3ffc57adde4d9844545ade97f93/packages/playground/website/public/logger.php). The logger API is a simple REST API that accepts a POST request with a `message` parameter.
-The API validates the message and then sends it to the [#playground-logs channel on the Making WordPress Slack](https://wordpress.slack.com/archives/C06Q5DCKZ3L).
-
-### Slack app
-
-[We use the Playground Slack app](https://api.slack.com/apps/A06PEFZ00SG) to send logs to the #playground-logs channel.
-
-The [Slack app OAuth token](https://api.slack.com/apps/A06PEFZ00SG/oauth?) and channel id are stored on Playground.WordPress.net as environment variables in `.htaccess`.
diff --git a/packages/docs/site/docs/13-contributing/09-contributor-day.md b/packages/docs/site/docs/13-contributing/09-contributor-day.md
new file mode 100644
index 0000000000..1c58ad06f6
--- /dev/null
+++ b/packages/docs/site/docs/13-contributing/09-contributor-day.md
@@ -0,0 +1,111 @@
+---
+slug: /wordcamp-contributor-day
+---
+
+# WordCamp Contributor Day
+
+The [WordPress Playground VS Code extension](https://marketplace.visualstudio.com/items?itemName=WordPressPlayground.wordpress-playground) and [wp-now](https://www.npmjs.com/package/@wp-now/wp-now) streamline the process of setting up a local WordPress environment. WordPress Playground powers both—no Docker, MySQL, or Apache required.
+
+Keep reading to learn how to use these tools for [local development](../05-local-development/01-wp-now.md) when contributing to WordPress. Please note that the extension and the NPM package are under development, and not all [Make WordPress teams](https://make.wordpress.org/) are fully supported.
+
+## Getting Started
+
+If you’re a visual learner, here’s a step-by-step video tutorial. If you prefer reading at your own pace, skip to the written instructions below.
+
+
+
+### VS Code Playground extension
+
+The [Visual Studio Code Playground extension](https://marketplace.visualstudio.com/items?itemName=WordPressPlayground.wordpress-playground) is a friendly zero-setup development environment.
+
+1. Open VS Code and navigate to the **Extensions** tab (**View > Extensions**).
+2. In the search bar, type _WordPress Playground_ and click **Install**.
+3. To interact with Playground, click the new icon in the **Activity Bar** and hit the **Start WordPress Server** button.
+4. A new tab will open in your browser within seconds.
+
+### wp-now NPM package
+
+`@wp-now/wp-now` is a CLI tool that allows you to spin up a WordPress site with a single command. No Docker, MySQL, or Apache are required.
+
+#### Prerequisites
+
+`wp-now` requires Node.js and NPM. If you haven’t yet, [download and install](https://nodejs.org/en/download) both before you begin.
+
+Depending on the Make WordPress team you contribute to, you may need a different Node.js version than the one you have installed. You can use Node Version Manager (NVM) to switch between versions. [Find the installation guide here](https://github.com/nvm-sh/nvm#installing-and-updating).
+
+#### Run wp-now
+
+You don’t have to install `wp-now` on your device to use it. Navigate to your plugin or theme directory and start `wp-now` with the following commands:
+
+```bash
+cd my-plugin-or-theme-directory
+npx @wp-now/wp-now start
+```
+
+## Ideas for contributors
+
+### Create a Gutenberg Pull Request (PR)
+
+1. Fork the [Gutenberg repository](https://github.com/WordPress/gutenberg) in your GitHub account.
+2. Then, clone the forked repository to download the files.
+3. Install the necessary dependencies and build the code in development mode.
+
+```bash
+git clone git@github.com:WordPress/gutenberg.git
+cd gutenberg
+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-now` replaces `wp-env`.
+
+:::
+
+Open a new terminal terminal tab, navigate to the Gutenberg directory, and start WordPress using `wp-now`:
+
+```bash
+cd gutenberg
+npx @wp-now/wp-now start
+```
+
+When you’re ready, commit and push your changes to your forked repository on GitHub and open a Pull Request on the Gutenberg repository.
+
+### Test a Gutenberg PR
+
+1. To test other Gutenberg PRs, checkout the branch associated with it.
+2. Pull the latest changes to ensure your local copy is up to date.
+3. Next, install the necessary dependencies, ensuring your testing environment matches the latest changes.
+4. Finally, build the code in development mode.
+
+```bash
+# copy the branch-name from GitHub #
+git checkout branch-name
+git pull
+npm install
+npm run dev
+
+# In a different terminal inside the Gutenberg directory *
+npx @wp-now/wp-now start
+```
+
+#### Test a Gutenberg PR with Playground in the browser
+
+You don’t need a local development environment to test Gutenberg PRs—use Playground to do it directly in the browser.
+
+1. Copy the ID of the PR you’d like to test (pick one from the [list of open Pull Requests](https://github.com/WordPress/gutenberg/pulls)).
+2. Open Playground’s [Gutenberg PR Previewer](https://playground.wordpress.net/gutenberg.html) and paste the ID you copied.
+3. Once you click **Go**, Playground will verify the PR is valid and open a new tab with the relevant PR, allowing you to review the proposed changes.
+
+## Translate WordPress Plugins with Playground in the browser
+
+You can translate supported WordPress Plugins by loading the plugin you want to translate and use Inline Translation. If the plugin developers have added the option, you'll find the **Translate Live** link on the top right toolbar of the translation view. You can read more about this exciting new option on [this Polyglots blog post](https://make.wordpress.org/polyglots/2023/05/08/translate-live-updates-to-the-translation-playground/).
+
+## Get help and contribute to WordPress Playground
+
+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 [Plaground Tools repository](https://github.com/WordPress/playground-tools/issues/new).
+- Share your feedback on the [**#meta-playground** Slack channel](https://wordpress.slack.com/archives/C04EWKGDJ0K).
diff --git a/packages/docs/site/docs/13-contributing/20-documentation.md b/packages/docs/site/docs/13-contributing/20-documentation.md
index 4e35a144d1..509ed7089a 100644
--- a/packages/docs/site/docs/13-contributing/20-documentation.md
+++ b/packages/docs/site/docs/13-contributing/20-documentation.md
@@ -1,71 +1,43 @@
-# Contributing Documentation
+# Documentation contributions
-WordPress Playground is documented by volunteers and we welcome your contributions.
+[WordPress Playground's documentation site](https://wordpress.github.io/wordpress-playground) is maintained by volunteers like you, who'd love your help.
-The [documentation tracking issue](https://github.com/WordPress/wordpress-playground/issues/772) contains a list of all documentation-related issues. It’s a good starting point to see what’s missing and what’s already there.
-
-Anything that you were missing when exploring Playground for the first time is a great addition to the documentation, even if it requires a fundamental change in how the documentation speaks to the user.
+All [documentation-related topics](https://github.com/WordPress/wordpress-playground/labels/%5BType%5D%20Documentation) are labeled `documentation`. Browse the list of open issues to find one you'd like to work on. Alternatively, if you believe something is missing from the current documentation, open an issue to discuss your suggestion.
## How can I contribute?
-### I am not familiar with Markdown
-
-If you are not familiar with Markdown, you can contribute by [opening an issue in the project repository](https://github.com/WordPress/wordpress-playground/issues/new) and describing what you would like to see added or changed.
-
-You could even write the content in the issue description and the project contributors will take care of the rest.
-
-### I am familiar with Markdown
-
-If you are familiar with [Markdown](https://www.markdownguide.org/), you can directly propose changes and new documentation pages by submitting a Pull Request. If you're not familiar with Pull Requests, read the [Collaborating with pull requests](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests) guide first.
-
-The existing documentation lives in the GitHub repository as Markdown files:
+You can contribute by [opening an issue in the project repository](https://github.com/WordPress/wordpress-playground/issues/new) and describing what you'd like to add or change.
-https://github.com/WordPress/wordpress-playground/tree/trunk/packages/docs/site/docs
+If you feel up to it, write the content in the issue description, and the project contributors will take care of the rest.
-Then, the documentation site is published here:
+### I'm familiar with markdown and GitHub
-https://wordpress.github.io/wordpress-playground
+If you are familiar with markdown, you can propose changes and new documentation pages by submitting a Pull Request.
-Some pages are written in [MDX](https://mdxjs.com/), which is Markdown with JSX. If you are not familiar with MDX, don't worry at all – you can still contribute to these pages by editing just the Markdown part.
+The documentation is stored in Playground's GitHub repository, [under `/packages/docs/site/docs`](https://github.com/WordPress/wordpress-playground/tree/trunk/packages/docs/site/docs).
-### Your first Pull Request
+## Edit in the browser
-#### An easy way to start
-
-Here's an easy way to start your first Pull Request:
-
-1. Go to https://github.com/WordPress/wordpress-playground/tree/trunk/packages/docs/site/docs
-2. Find the page you'd like to edit or a directory where you'd like to add a new page
-3. Click the "Add Files" button to add a new file, or click on an existing file and then click the pencil icon to edit it
-4. GitHub will ask you to fork the repository and create a new branch for your changes – do that
-5. An editor will open where you can make your changes
-6. When you're done, click the Commit Changes button and start a Pull Request
+1. Find the page you'd like to edit or the directory of the chapter you'd like to add a new page to.
+2. Click the **Add Files** button to add a new file, or click on an existing file and then click the pencil icon to edit it.
+3. GitHub will ask you to fork the repository and create a new branch with your changes.
+4. An editor will open where you can make the changes.
+5. When you're done, click the **Commit Changes** button and submit a Pull Request.
That's it! You've just contributed to the WordPress Playground documentation.
-The upside of this approach is that you don't need to clone the repository, set up a local development environment, or run any commands. You can edit the documentation directly in your browser.
+This approach means you don't need to clone the repository, set up a local development environment, or run any commands.
-The downside is that you won't be able to preview your changes on the documentation site. Previewing is not critical and you can be a successful contributor without it, but if you'd still like to see your changes before submitting a Pull Request, follow the instructions below.
+The downside is that you won't be able to preview your changes. Keep reading to learn how to review your changes before submitting a Pull Request.
-#### A more difficult way with a preview
+### Local preview
-If you'd like to a preview of your changes, you'll need to clone the repository and run the following commands:
+Clone the repository and navigate to the directory on your device. Now run the following commands:
```bash
-npm install -g nx
npm install
-nx dev docs-site
+npm run build:docs
+npm run dev:docs
```
-This will start a local server where you can preview your changes. From there, you can edit the documentation files
-in your code editor and see the changes in real-time.
-
-## What to contribute?
-
-See the [documentation tracking issue](https://github.com/WordPress/wordpress-playground/issues/772) for an up to date list of specific tasks and documentation pages that need to be written.
-
-## General guidelines
-
-- Document any limitations you run into at https://wordpress.github.io/wordpress-playground/limitations/
-- The documentation structure needs brushing up, you are welcome to move pages around and propose new structures
-- Use simple language and avoid jargon
+The documentation site opens in a new browser tab and refreshes automatically with each change. Continue to edit the relevant file in your code editor and test the changes in real-time.
diff --git a/packages/docs/site/docs/14-contributor-day/01-index.md b/packages/docs/site/docs/14-contributor-day/01-index.md
deleted file mode 100644
index 637f875a26..0000000000
--- a/packages/docs/site/docs/14-contributor-day/01-index.md
+++ /dev/null
@@ -1,116 +0,0 @@
----
-title: WordCamp Contributor Day
-slug: /wordcamp-contributor-day
----
-
-# WordCamp Contributor Day
-
-The WordPress Playground VS Code extension and wp-now are tools that streamline the process of setting up a local WordPress environment. Both are powered by WordPress Playground, eliminating the need for other tools like Docker and MySQL.
-
-Read on to see how you can use either for contributing to WordPress. Please note that they’re currently in an alpha state and not all Make teams are fully supported.
-
-## Getting Started
-
-If you're a visual learner – here's a step-by-step video for you! If you prefer reading at your own pace, you're welcome to skip over to the written instructions below.
-
-
-
-### VSCode Playground extension
-
-[Visual Studio Code Playground extension](https://marketplace.visualstudio.com/items?itemName=WordPressPlayground.wordpress-playground) offers a friendly user interface to a local WordPress environment.
-
-To get started, open your Visual Studio Code and navigate to the extensions tab. In the search bar, type 'WordPress playground' and click 'Install'. This will add a new icon on your sidebar.
-
-## wp-now
-
-### Minimum Requirements
-
-To get started with wp-now, you need to have Node and npm installed on your system. You can follow this guide to install them: [Node and npm installation guide](https://nodejs.org/en/download/package-manager). We also recommend using nvm to easily change the node version: [nvm installation guide](https://github.com/nvm-sh/nvm#installing-and-updating).
-
-### Installing
-
-You can globally install wp-now npm package in your machine, or if you prefer, you can run these commands directly from your browser using GitHub codespaces.: [https://www.npmjs.com/package/@wp-now/wp-now](https://www.npmjs.com/package/@wp-now/wp-now).
-
-```
-npm install -g @wp-now/wp-now
-```
-
-### Running
-
-To start a new server, navigate to your WordPress plugin or theme directory and run the command wp-now start. This will start the server with the default PHP and WordPress versions. A new tab will open automatically in your browser.
-
-```
-cd gutenberg
-wp-now start
-```
-
-You can stop wp-now by killing the process by pressing the keys `CTRL + C`.
-
-To change the PHP or WordPress version, you can use the `--php` and `--wp` arguments. For example, to start a server with PHP 7.4 and WordPress 6.1, you can run:
-
-```
-wp-now start --php 7.4 --wp 6.1
-```
-
-## Contributing to Gutenberg
-
-### Create a Gutenberg PR Step By Step
-
-Begin by creating a fork of the Gutenberg repository using your GitHub account. Once you've done that, clone your forked repository to your local machine to download the code. Following this, install the necessary dependencies and build the Gutenberg files.
-
-```
-git clone git@github.com:WordPress/gutenberg.git
-cd gutenberg
-npm install
-npm run dev
-```
-
-Ensure that wp-now is installed on your system. Then, open a new terminal window and start the WordPress server by executing the wp-now command.
-
-```
-cd gutenberg
-wp-now start
-```
-
-Commit and push your changes to your forked repository on GitHub and create a new pull request on the Gutenberg repository.
-
-For more in detail information, check the block editor handbook: https://developer.wordpress.org/block-editor/contributors/code/getting-started-with-code-contribution/#getting-the-gutenberg-code
-
-### Test a Gutenberg PR Step By Step
-
-To test a Gutenberg PR with wp-now, start by navigating to the PR on the Gutenberg repository. Once there, checkout the PR branch to switch your local environment to the version of the code that includes the proposed changes. After checking out the branch, pull the latest changes to ensure your local copy is up to date. Next, run npm install to ensure all dependencies are up to date. This step is crucial as it ensures that your testing environment matches the one in which the changes were made. Finally, test the changes in your local environment. This could involve running unit tests and manually testing features in a browser.
-
-```
-# copy the branch-name from GitHub
-git checkout branch-name
-git pull
-npm install
-npm run dev
-
-# In a different terminal inside the gutenberg folder
-wp-now start
-```
-
-### Test a Gutenberg PR with the web version of WordPress Playground
-
-You can manually test a Gutenberg pull request directly from your browser. Given a pull request URL, https://github.com/WordPress/gutenberg/pull/51239, copy the ID (in this case, `51239`) and paste it at https://playground.wordpress.net/gutenberg.html. Use your specific pull request ID. Once you press "Go," your Pull Request will open in a new WordPress Playground where you can review the proposed changes!
-
-
-
-## Translate WordPress Plugins using the WordPress Playground
-
-You can translate WordPress Plugins and Themes the traditional way in the table view at https://translate.wordpress.org/, or you can load the plugin to be translated and use Inline Translation to do so. Find the `Translate Live` link on the top right of the translation view for this. See [this blog post for more context](https://make.wordpress.org/polyglots/2023/05/08/translate-live-updates-to-the-translation-playground/).
-
-## Contributing to other Make projects
-
-At this time, contributing to other Make projects is not fully supported at this time.
-
-## Known Limitations
-
-wp-now is in alpha version. Check out the known issues [https://github.com/WordPress/playground-tools/blob/trunk/packages/wp-now/README.md#known-issues](https://github.com/WordPress/playground-tools/blob/trunk/packages/wp-now/README.md#known-issues).
-
-## Getting Help and Contributing to WordPress Playground
-
-If you encounter any issues when running your project with 'wp-now' or the VSCode Playground extension, don't hesitate to reach out to the Playground table or ask in the #meta-playground Slack channel. Someone will be around to assist you during the day.
-
-If you come across a bug or if you have an idea for a potential feature, we encourage you to share your input. You can create an issue on our GitHub repository at [https://github.com/WordPress/playground-tools](https://github.com/WordPress/playground-tools). Alternatively, you can share your thoughts in the ‘#meta-playground’ channel on Slack.
diff --git a/packages/docs/site/docs/16-faq.md b/packages/docs/site/docs/16-faq.md
deleted file mode 100644
index f226c4a917..0000000000
--- a/packages/docs/site/docs/16-faq.md
+++ /dev/null
@@ -1,18 +0,0 @@
----
-title: FAQ
-slug: /faq
----
-
-# FAQ
-
-## Wait, where is PHP running?
-
-In your browser! It is mindblowing, isn't it? There's a new technology called WebAssembly that makes it possible. You can learn more in [this article on web.dev](https://web.dev/wordpress-playground/).
-
-## Is WordPress Playground available in another language?
-
-Yes! Although it requires some work at the moment. You need to tell Playground to download and install the translation files and one way to do it is using [the Blueprints API](https://make.wordpress.org/polyglots/2023/05/08/translate-live-updates-to-the-translation-playground/). There is no step-by-step tutorial yet, but you can learn by reading the source of [Playground+Translations plugin](https://translate.wordpress.org/projects/wp-plugins/friends/dev/en-gb/default/playground/) [(GitHub link)](https://github.com/akirk/wp-glotpress-playground/blob/main/index.php).
-
-## Will WP-CLI be supported?
-
-Yes! Some commands already work if you include `wp-cli.phar` in the executed PHP code, and support for others is work in progress. The documentation will be progressively updated to reflect the progress.
diff --git a/packages/docs/site/docs/_fragments/_limitations_ui.md b/packages/docs/site/docs/_fragments/_limitations_ui.md
deleted file mode 100644
index 61883c3934..0000000000
--- a/packages/docs/site/docs/_fragments/_limitations_ui.md
+++ /dev/null
@@ -1,13 +0,0 @@
-### You can't access the Plugins or Themes Directory in the browser
-
-The web version of WordPress does not support network connections, so the plugin directory in wp-admin is not available. However, you can still upload plugins and open them with "?plugin=coblocks" or a similar query string.
-
-You can track the progress of adding network support in the browser at https://github.com/WordPress/wordpress-playground/issues/85.
-
-### When you refresh the page, you'll lose anything you did (unless you export it)
-
-In the web version of WordPress Playground, all database changes and uploads are gone once the page is refreshed. Preserving them would be useful for courses, technical demos, even sharing a link to your changes.
-
-Be sure to [export your work](../02-start-using/01-index.md#save-your-site) before you close the page.
-
-You can track the progress of support for persisting the changes at https://github.com/WordPress/wordpress-playground/issues/19
diff --git a/packages/docs/site/docs/_fragments/_wp_now_overview.mdx b/packages/docs/site/docs/_fragments/_wp_now_overview.mdx
deleted file mode 100644
index 6f675d8925..0000000000
--- a/packages/docs/site/docs/_fragments/_wp_now_overview.mdx
+++ /dev/null
@@ -1,9 +0,0 @@
-`wp-now` is a CLI tool that allows you to quickly spin up a WordPress site with a single command. Similarly to the VS Code extension, it uses a portable WebAssembly version of PHP and SQLite. No Docker, MySQL, or Apache is required.
-
-To install `wp-now` directly from `npm`:
-
-```bash
-npm install -g @wp-now/wp-now
-cd wordpress-plugin-or-theme
-wp-now start
-```
diff --git a/packages/playground/blueprints/src/lib/steps/define-site-url.ts b/packages/playground/blueprints/src/lib/steps/define-site-url.ts
index 5db0e405b4..45d80d7172 100644
--- a/packages/playground/blueprints/src/lib/steps/define-site-url.ts
+++ b/packages/playground/blueprints/src/lib/steps/define-site-url.ts
@@ -13,10 +13,10 @@ export interface DefineSiteUrlStep {
}
/**
- * Sets WP_HOME and WP_SITEURL constants for the WordPress installation.
+ * Sets [`WP_HOME`](https://developer.wordpress.org/advanced-administration/wordpress/wp-config/#blog-address-url) and [`WP_SITEURL`](https://developer.wordpress.org/advanced-administration/wordpress/wp-config/#wp-siteurl) constants for the WordPress installation.
*
- * Beware: Using this step makes no sense on playground.wordpress.net.
- * It is useful when you're building a custom Playground-based tool like wp-now,
+ * Using this step on playground.wordpress.net is moot.
+ * It is useful when building a custom Playground-based tool, like [`wp-now`](https://www.npmjs.com/package/@wp-now/wp-now),
* or deploying Playground on a custom domain.
*
* @param playground The playground client.
diff --git a/packages/playground/blueprints/src/lib/steps/define-wp-config-consts.ts b/packages/playground/blueprints/src/lib/steps/define-wp-config-consts.ts
index 4a9151efef..469bd67b2d 100644
--- a/packages/playground/blueprints/src/lib/steps/define-wp-config-consts.ts
+++ b/packages/playground/blueprints/src/lib/steps/define-wp-config-consts.ts
@@ -23,13 +23,14 @@ export interface DefineWpConfigConstsStep {
/** The constants to define */
consts: Record;
/**
- * The method of defining the constants. Possible values are:
+ * The method of defining the constants in wp-config.php. Possible values are:
*
* - rewrite-wp-config: Default. Rewrites the wp-config.php file to
* explicitly call define() with the requested
* name and value. This method alters the file
* on the disk, but it doesn't conflict with
* existing define() calls in wp-config.php.
+ *
* - define-before-run: Defines the constant before running the requested
* script. It doesn't alter any files on the disk, but
* constants defined this way may conflict with existing
@@ -45,7 +46,7 @@ export interface DefineWpConfigConstsStep {
}
/**
- * Defines constants in a wp-config.php file.
+ * Defines constants in a [`wp-config.php`](https://developer.wordpress.org/advanced-administration/wordpress/wp-config/) file.
*
* This step can be called multiple times, and the constants will be merged.
*
diff --git a/packages/playground/blueprints/src/lib/steps/enable-multisite.ts b/packages/playground/blueprints/src/lib/steps/enable-multisite.ts
index a728b98414..03c76c3e52 100644
--- a/packages/playground/blueprints/src/lib/steps/enable-multisite.ts
+++ b/packages/playground/blueprints/src/lib/steps/enable-multisite.ts
@@ -24,7 +24,7 @@ export interface EnableMultisiteStep {
}
/**
- * Defines constants in a wp-config.php file.
+ * Defines the [Multisite](https://developer.wordpress.org/advanced-administration/multisite/create-network/) constants in a `wp-config.php` file.
*
* This step can be called multiple times, and the constants will be merged.
*
diff --git a/packages/playground/blueprints/src/lib/steps/import-wordpress-files.ts b/packages/playground/blueprints/src/lib/steps/import-wordpress-files.ts
index 5b85c7725d..b4bac154c2 100644
--- a/packages/playground/blueprints/src/lib/steps/import-wordpress-files.ts
+++ b/packages/playground/blueprints/src/lib/steps/import-wordpress-files.ts
@@ -34,9 +34,9 @@ export interface ImportWordPressFilesStep {
/**
* Imports top-level WordPress files from a given zip file into
- * the documentRoot. For example, if a zip file contains the
+ * the `documentRoot`. For example, if a zip file contains the
* `wp-content` and `wp-includes` directories, they will replace
- * the corresponding directories in Playground's documentRoot.
+ * the corresponding directories in Playground's `documentRoot`.
*
* Any files that Playground recognizes as "excluded from the export"
* will carry over from the existing document root into the imported
diff --git a/packages/playground/blueprints/src/lib/steps/login.ts b/packages/playground/blueprints/src/lib/steps/login.ts
index 31e7ee6dca..824b18cb59 100644
--- a/packages/playground/blueprints/src/lib/steps/login.ts
+++ b/packages/playground/blueprints/src/lib/steps/login.ts
@@ -27,8 +27,8 @@ export type LoginStep = {
};
/**
- * Logs in to the Playground.
- * Under the hood, this function submits the wp-login.php form
+ * Logs in to Playground.
+ * Under the hood, this function submits the [`wp-login.php`](https://developer.wordpress.org/reference/files/wp-login.php/) [form](https://developer.wordpress.org/reference/functions/wp_login_form/)
* just like a user would.
*/
export const login: StepHandler = async (
diff --git a/packages/playground/blueprints/src/lib/steps/request.ts b/packages/playground/blueprints/src/lib/steps/request.ts
index d001eddbd7..cceb994ad8 100644
--- a/packages/playground/blueprints/src/lib/steps/request.ts
+++ b/packages/playground/blueprints/src/lib/steps/request.ts
@@ -32,7 +32,7 @@ export interface RequestStep {
}
/**
- * Sends a HTTP request to the Playground.
+ * Sends a HTTP request to Playground.
*/
export const request: StepHandler> = async (
playground,
diff --git a/packages/playground/blueprints/src/lib/steps/run-php-with-options.ts b/packages/playground/blueprints/src/lib/steps/run-php-with-options.ts
index 72181d178f..ae382b2c9d 100644
--- a/packages/playground/blueprints/src/lib/steps/run-php-with-options.ts
+++ b/packages/playground/blueprints/src/lib/steps/run-php-with-options.ts
@@ -21,7 +21,7 @@ import { PHPRunOptions } from '@php-wasm/universal';
export interface RunPHPWithOptionsStep {
step: 'runPHPWithOptions';
/**
- * Run options (See /wordpress-playground/api/universal/interface/PHPRunOptions)
+ * Run options (See /wordpress-playground/api/universal/interface/PHPRunOptions/))
*/
options: PHPRunOptions;
}
diff --git a/packages/playground/blueprints/src/lib/steps/run-php.ts b/packages/playground/blueprints/src/lib/steps/run-php.ts
index fa90cd31d2..c671cf4840 100644
--- a/packages/playground/blueprints/src/lib/steps/run-php.ts
+++ b/packages/playground/blueprints/src/lib/steps/run-php.ts
@@ -22,6 +22,7 @@ export interface RunPHPStep {
/**
* Runs PHP code.
+ * When running WordPress functions, the `code` key must first load [`wp-load.php`](https://github.com/WordPress/WordPress/blob/master/wp-load.php) and start with `"> = async (
playground,
diff --git a/packages/playground/blueprints/src/lib/steps/site-data.ts b/packages/playground/blueprints/src/lib/steps/site-data.ts
index 768c399467..6e4533bfca 100644
--- a/packages/playground/blueprints/src/lib/steps/site-data.ts
+++ b/packages/playground/blueprints/src/lib/steps/site-data.ts
@@ -25,8 +25,8 @@ export type SetSiteOptionsStep = {
};
/**
- * Sets site options. This is equivalent to calling `update_option` for each
- * option in the `options` object.
+ * Sets site options. This is equivalent to calling [`update_option`](https://developer.wordpress.org/reference/functions/update_option/) for each
+ * option in the [`options`](https://developer.wordpress.org/apis/options/#available-options-by-category) object.
*/
export const setSiteOptions: StepHandler = async (
php,
@@ -71,7 +71,7 @@ export interface UpdateUserMetaStep {
}
/**
- * Updates user meta. This is equivalent to calling `update_user_meta` for each
+ * Updates user meta. This is equivalent to calling [`update_user_meta`](https://developer.wordpress.org/reference/functions/update_user_meta/) for each
* meta value in the `meta` object.
*/
export const updateUserMeta: StepHandler = async (
diff --git a/packages/playground/blueprints/src/lib/steps/wp-cli.ts b/packages/playground/blueprints/src/lib/steps/wp-cli.ts
index bb7622d915..c6c7397cc5 100644
--- a/packages/playground/blueprints/src/lib/steps/wp-cli.ts
+++ b/packages/playground/blueprints/src/lib/steps/wp-cli.ts
@@ -24,7 +24,7 @@ export interface WPCLIStep {
}
/**
- * Runs PHP code.
+ * Runs PHP code using [WP-CLI](https://developer.wordpress.org/cli/commands/).
*/
export const wpCLI: StepHandler> = async (
playground,