Reorganize and update documentation (#1354)

## What is this PR doing? 1. Reorganizing the **Contributing** chapter of the docs, and updating the content. See [this issue](adamziel/playground-docs-workflow#31 (comment)) 2. Adding references to [the Developer docs](https://developer.wordpress.org/) in relevant Blueprints steps. See #1291. ~### To-Do:~ - [x] Update [wp-now](https://www.npmjs.com/package/@wp-now/wp-now) README. **Done** in [Update wp-now documentation #251](WordPress/playground-tools#251). ## Testing Instructions 1. Build the site (standard `npm run build` to update the steps in `packages/playground/blueprints/src/lib/steps/`) 2. Run `npm run dev:docs`. 3. Review the changes. @adamziel
WordPress · May 1, 2024 · dbcdf65 · dbcdf65
1 parent f06f522
commit dbcdf65
Show file tree

Hide file tree

Showing 36 changed files with 382 additions and 560 deletions.
diff --git a/package.json b/package.json
@@ -6,6 +6,7 @@
 		"build": "nx run-many --all --target=build",
 		"build:website": "nx build playground-website",
 		"build:docs": "nx build docs-site",
+		"dev:docs": "nx dev docs-site",
 		"changelog": "bun ./packages/meta/bin/update-changelog.ts; cp CHANGELOG.md packages/docs/site/docs/17-changelog.md",
 		"deploy:docs": "gh-pages -d dist/docs/build -t true",
 		"dev": "nx dev playground-website",

diff --git a/packages/docs/site/docs/01-start-here/01-index.md b/packages/docs/site/docs/01-start-here/01-index.md
@@ -24,9 +24,9 @@ This site (Documentation) is where you will find all the information you need to
 
 -   [Start using WordPress Playground](../02-start-using/01-index.md) in 5 minutes (and check out the [demo site](https://playground.wordpress.net/))
 -   [Build your first app](../03-build-an-app/01-index.md) with WordPress Playground
--   Use Playground as a zero-setup [local development environment](../04-nodejs/01-index.md#start-a-zero-setup-dev-environment-via-vscode-extension)
+-   Use Playground as a zero-setup [local development environment](../05-local-development/02-vscode-extension.md)
 -   Read about the [limitations](../12-limitations/01-index.md)
--   [WordCamp Contributor Day](../14-contributor-day/01-index.md)
+-   [WordCamp Contributor Day](../13-contributing/09-contributor-day.md)
 
 ## Take a deep dive
 

diff --git a/packages/docs/site/docs/04-nodejs/01-index.md b/packages/docs/site/docs/04-nodejs/01-index.md
diff --git a/packages/docs/site/docs/05-local-development/01-wp-now.md b/packages/docs/site/docs/05-local-development/01-wp-now.md
@@ -0,0 +1,41 @@
+---
+slug: wp-now
+---
+
+# wp-now NPM package
+
+[`@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](/05-local-development/02-vscode-extension.md), it uses a portable WebAssembly version of PHP and SQLite. No Docker, MySQL, or Apache are required.
+
+## Launch wp-now in a plugin or theme directory
+
+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
+```
+
+## Launch wp-now in the `wp-content` directory with options
+
+You can also start `wp-now` from any `wp-content` folder. The following example passes parameters for changing the PHP and WordPress versions and loading a blueprint file.
+
+```bash
+cd my-wordpress-folder/wp-content
+npx @wp-now/wp-now start --wp=6.4 --php=8.0 --blueprint=path/to/blueprint.json
+```
+
+:::info **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).
+
+:::
+
+## Install wp-now globally
+
+Alternatively, you can install `@wp-now/wp-now` globally to load it from any directory:
+
+```bash
+npm install -g @wp-now/wp-now
+cd my-plugin-or-theme-directory
+wp-now start
+```
diff --git a/packages/docs/site/docs/05-local-development/02-vscode-extension.md b/packages/docs/site/docs/05-local-development/02-vscode-extension.md
@@ -0,0 +1,16 @@
+# VS Code extension
+
+Start a zero-setup development environment using the [VS Code extension](https://marketplace.visualstudio.com/items?itemName=WordPressPlayground.wordpress-playground), and develop your plugin or theme locally without installing Apache or MySQL.
+
+:::info **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).
+
+:::
+
+The extension ships with a portable WebAssembly version of PHP and sets up WordPress to use SQLite. Once installed, all you have to do is click the **Start WordPress Server** button in VS Code:
+
+import Image from '@theme/IdealImage';
+import vsCodeScreenshot from '@site/static/img/start-wordpress-server.png';
+
+<div style={{maxWidth:350}}><Image img={vsCodeScreenshot} /></div>
diff --git a/packages/docs/site/docs/05-local-development/03-php-wasm-node.md b/packages/docs/site/docs/05-local-development/03-php-wasm-node.md
@@ -0,0 +1,19 @@
+---
+title: php-wasm/node
+---
+
+# Using WordPress Playground in Node.js
+
+As a WebAssembly project, you can also use WordPress Playground in Node.js.
+
+If you need low-level control over the underlying WebAssembly PHP build, take a look at the [`@php-wasm/node` package](https://npmjs.org/@php-wasm/node) which ships the PHP WebAssembly runtime. This package is at the core of all WordPress Playground tools for Node.js.
+
+:::info **API reference**
+
+Consult the [complete list](/api/node) of Classes, Functions, Interfaces, and Type Aliases.
+
+:::
+
+import PHPWASMNode from '@php-wasm/node/\README.md';
+
+<PHPWASMNode />
diff --git a/packages/docs/site/docs/05-local-development/_category_.json b/packages/docs/site/docs/05-local-development/_category_.json
@@ -0,0 +1,3 @@
+{
+	"label": "Local Development"
+}
diff --git a/packages/docs/site/docs/06-playground-apis/02-api-concepts.md b/packages/docs/site/docs/06-playground-apis/02-api-concepts.md
@@ -6,7 +6,7 @@ title: Concepts
 
 WordPress Playground in the browser is all about links and iframes. Regardless of which API you choose, you will use it in one of the following ways:
 
-### Link to the Playground site
+## Link to the Playground site
 
 You can customize WordPress Playground by modifying the https://playground.wordpress.net/ link. You can, for example, create a post, request a specific plugin, or run any PHP code.
 

diff --git a/packages/docs/site/docs/11-architecture/01-index.md b/packages/docs/site/docs/11-architecture/01-index.md
@@ -1,4 +1,4 @@
-# Architecture Overview
+# Architecture overview
 
 WordPress Playground consists of the following high-level components:
 
@@ -9,3 +9,22 @@ WordPress Playground consists of the following high-level components:
 -   [Public API](../06-playground-apis/01-index.md)
 
 Visit each section to learn more about the specific parts of the architecture.
+
+## Tooling
+
+### NX: building packages and projects
+
+WordPress Playground uses [NX](https://nx.dev/), a build system designed for monorepos.
+
+The dependencies between Playground packages and projects [are too complex](https://github.com/WordPress/wordpress-playground/pull/151) for a bundler like Webpack, and NX handles this complexity much better:
+![Dependency graph](@site/static/img/dependencies.png)
+
+To learn more, head over to the [NX developer docs](https://nx.dev/getting-started/intro).
+
+### Lerna: publishing packages and projects
+
+WordPress Playground includes several NPM packages, a VS Code extension, WordPress plugins, a web app, and other GitHub releases, all managed across two monorepos: the main [wordpress-playground](https://github.com/WordPress/wordpress-playground) and [Playground Tools](https://github.com/WordPress/playground-tools/).
+
+We use [Lerna](https://lerna.js.org) to build, manage, and publish all JavaScript/TypeScript packages. Lerna handles everything simultaneously: it increments the version number, sets a new tag, and publishes the modified packages to `npm`.
+
+The published packages share the same version number, so when updating a single package, Lerna bumps the version number of all dependent packages.
diff --git a/packages/docs/site/docs/11-architecture/10-browser-iframe-rendering.md b/packages/docs/site/docs/11-architecture/10-browser-iframe-rendering.md
@@ -1,24 +1,32 @@
 # Iframe-based rendering
 
-All the PHPRequestHandler responses must be rendered in an iframe to avoid reloading the page. Remember, the entire setup only lives as long as the main `index.html`. We want to avoid reloading the main app at all cost.
+To avoid page reloads, all the `PHPRequestHandler` responses must be rendered in an iframe. Remember, the entire setup only lives as long as the main `index.html`. We want to avoid reloading the main app at all costs.
 
 In our app example above, `index.php` renders the following HTML:
 
 ```html
 <a href="page.php">Go to page.php</a>
 ```
 
-Imagine our `index.html` rendered it in a `<div>` instead of an `<iframe>`. As soon as you clicked on that link, the browser would try to navigate from `index.html` to `page.php`. However, `index.html` runs the entire PHP app including the Worker Thread, the PHPRequestHandler, and the traffic control connecting them to the Service Worker. Navigating away from it would destroy the app.
+Imagine our `index.html` rendered it in a `<div>` instead of an `<iframe>`. As soon as you click on that link, the browser will try to navigate from `index.html` to `page.php`. However, `index.html` runs the entire PHP app, including the Worker Thread, the PHPRequestHandler, and the traffic control connecting them to the Service Worker. Navigating away from it would destroy the app.
 
 Now, consider an iframe with the same link in it:
 
 ```html
 <iframe srcdoc='<a href="page.php">Go to page.php</a>'></iframe>
 ```
 
-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 `<a target="_top">Click here</a>` 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
@@ -1,22 +1,18 @@
----
-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?
 
 Behind the scenes, the official [SQLite Database Integration](https://github.com/WordPress/sqlite-database-integration) plugin intercepts all MySQL queries and rewrites them in SQLite dialect. The x.0 release ships [a new WordPress Playground-informed translation layer](https://github.com/WordPress/sqlite-database-integration/pull/9) that allows WordPress on SQLite to pass 99% of the WordPress unit test suite.
 
 ## 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
@@ -58,6 +58,7 @@ git clone -b trunk --single-branch --depth 1 [email protected]: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
@@ -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
 
-<Limitations />
+### 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 `<a target="_top">Click here</a>` 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": "<?php require_once('wordpress/wp-load.php'); OTHER_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
@@ -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.