WordPress · fellyph · Apr 6, 2026 · Apr 6, 2026 · Apr 6, 2026 · Apr 6, 2026
diff --git a/packages/docs/site/docs/_fragments/_api_list.mdx b/packages/docs/site/docs/_fragments/_api_list.mdx
diff --git a/packages/docs/site/docs/_fragments/_js_api_short_example.mdx b/packages/docs/site/docs/_fragments/_js_api_short_example.mdx
diff --git a/packages/docs/site/docs/_fragments/_playground_wp_net_may_stop_working.md b/packages/docs/site/docs/_fragments/_playground_wp_net_may_stop_working.md
diff --git a/packages/docs/site/docs/_fragments/_this_is_query_api.md b/packages/docs/site/docs/_fragments/_this_is_query_api.md
diff --git a/packages/docs/site/docs/_fragments/_work_in_progress.md b/packages/docs/site/docs/_fragments/_work_in_progress.md
diff --git a/packages/docs/site/docs/developers/03-build-an-app/01-index.md b/packages/docs/site/docs/developers/03-build-an-app/01-index.md
@@ -22,26 +22,28 @@ Playground can be embedded on your website using the HTML `<iframe>` tag as foll
 
 Every visitor will get their own private WordPress instance for free. You can then customize it using one of the [Playground APIs](/developers/apis/).
 
-import PlaygroundWpNetWarning from '@site/docs/\_fragments/\_playground_wp_net_may_stop_working.md';
+:::caution Careful with the demo site
 
-<PlaygroundWpNetWarning />
+The site at https://playground.wordpress.net is there to support the community, but there are no guarantees it will continue to work if the traffic grows significantly.
+
+If you need certain availability, you should [host your own WordPress Playground](/developers/architecture/host-your-own-playground).
+
+:::
 
 ## Control the embedded website
 
 WordPress Playground provides three APIs you can use to control the iframed website. All the examples in this section are built using one of these:
 
-import APIList from '@site/docs/\_fragments/\_api_list.mdx';
-
-<APIList />
+- [Query API](/developers/apis/query-api) enable basic operations using only query parameters
+- [Blueprints API](/blueprints) give you a great degree of control with a simple JSON file
+- [JavaScript API](/developers/apis/javascript-api) give you full control via a JavaScript client from an npm package
 
 Learn more about each of these APIs in the [APIs overview section](/developers/apis/).
 
 ## Showcase a plugin or theme from WordPress directory
 
-import ThisIsQueryApi from '@site/docs/\_fragments/\_this_is_query_api.md';
-
 You can install plugins and themes from the WordPress directory with only URL parameters. This iframe preinstalls the `coblocks` and `friends` plugins and the `pendant` theme.
-<ThisIsQueryApi />
+This is called [Query API](/developers/apis/query-api/) and you can learn more about it [here](/developers/apis/query-api/).
 
 ```html
 <iframe src="https://playground.wordpress.net/?plugin=coblocks"></iframe>

diff --git a/packages/docs/site/docs/developers/06-apis/01-index.md b/packages/docs/site/docs/developers/06-apis/01-index.md
@@ -3,8 +3,6 @@ title: APIs overview
 slug: /developers/apis/
 ---
 
-import ThisIsQueryApi from '@site/docs/\_fragments/\_this_is_query_api.md';
-
 ## WordPress Playground APIs overview
 
 WordPress Playground exposes a few APIs that you can use to interact with the Playground:
@@ -23,7 +21,7 @@ Or a theme:
 
 [https://playground.wordpress.net/?theme=pendant](https://playground.wordpress.net/?theme=pendant)
 
-<ThisIsQueryApi /> Once you have a URL that you like, you can embed it in your website using an iframe:
+This is called [Query API](/developers/apis/query-api/) and you can learn more about it [here](/developers/apis/query-api/). Once you have a URL that you like, you can embed it in your website using an iframe:
 
 ```html
 <iframe style="width: 800px; height: 500px;" src="https://playground.wordpress.net/?plugin=coblocks"></iframe>
@@ -97,9 +95,20 @@ Blueprints play a significant role in WordPress Playground, so they have their o
 
 The `@wp-playground/client` package provides a JavaScript API you can use to fully control your Playground instance. Here's a simple example of what you can do:
 
-import JSApiShortExample from '@site/docs/\_fragments/\_js_api_short_example.mdx';
-
-<JSApiShortExample />
+```html
+<iframe id="wp" style="width: 100%; height: 300px; border: 1px solid #000;"></iframe>
+<script type="module">
+	// Use unpkg for convenience
+	import { startPlaygroundWeb } from 'https://playground.wordpress.net/client/index.js';
+
+	const client = await startPlaygroundWeb({
+		iframe: document.getElementById('wp'),
+		remoteUrl: `https://playground.wordpress.net/remote.html`,
+	});
+	// Let's wait until Playground is fully loaded
+	await client.isReady();
+</script>
+```
 
 :::info
 Check the [JavaScript API](/developers/apis/javascript-api/) section for more info.
@@ -127,28 +136,32 @@ WordPress Playground can be embedded in your app using an `<iframe>`:
 
 To customize that Playground instance, you can:
 
--   Load it from special link prepared using the [Query API](/developers/apis/query-api) (easy) or the [JSON Blueprints API](/blueprints) (medium).
--   Control it using the [JavaScript API](/developers/apis/javascript-api/).
+- Load it from special link prepared using the [Query API](/developers/apis/query-api) (easy) or the [JSON Blueprints API](/blueprints) (medium).
+- Control it using the [JavaScript API](/developers/apis/javascript-api/).
 
 The JavaScript API gives you the most control, but it is also the least convenient option as it requires loading the Playground Client library.
 
-import PlaygroundWpNetWarning from '@site/docs/\_fragments/\_playground_wp_net_may_stop_working.md';
+:::caution Careful with the demo site
 
-<PlaygroundWpNetWarning />
+The site at https://playground.wordpress.net is there to support the community, but there are no guarantees it will continue to work if the traffic grows significantly.
+
+If you need certain availability, you should [host your own WordPress Playground](/developers/architecture/host-your-own-playground).
+
+:::
 
 ### Browser APIs
 
 The following Playground APIs are available in the browser:
 
-import APIList from '@site/docs/\_fragments/\_api_list.mdx';
-
-<APIList />
+- [Query API](/developers/apis/query-api) enable basic operations using only query parameters
+- [Blueprints API](/blueprints) give you a great degree of control with a simple JSON file
+- [JavaScript API](/developers/apis/javascript-api) give you full control via a JavaScript client from an npm package
 
 ### In Node.js
 
 The following Playground APIs are available in Node.js:
 
--   [JSON Blueprints API](/blueprints)
--   [JavaScript API](/developers/apis/javascript-api/)
+- [JSON Blueprints API](/blueprints)
+- [JavaScript API](/developers/apis/javascript-api/)
 
 These APIs are very similar to their web counterparts, but, unsurprisingly, they are not based or links or iframes.
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
@@ -18,14 +18,25 @@ call inside JavaScript. This is **not** a network-based REST API.
 
 To use the JavaScript API, you'll need:
 
--   An `<iframe>` element
--   The `@wp-playground/client` package (from npm or a CDN)
+- An `<iframe>` element
+- The `@wp-playground/client` package (from npm or a CDN)
 
 Here's the shortest example of how to use the JavaScript API in a HTML page:
 
-import JSApiShortExample from '@site/docs/\_fragments/\_js_api_short_example.mdx';
-
-<JSApiShortExample />
+```html
+<iframe id="wp" style="width: 100%; height: 300px; border: 1px solid #000;"></iframe>
+<script type="module">
+	// Use unpkg for convenience
+	import { startPlaygroundWeb } from 'https://playground.wordpress.net/client/index.js';
+
+	const client = await startPlaygroundWeb({
+		iframe: document.getElementById('wp'),
+		remoteUrl: `https://playground.wordpress.net/remote.html`,
+	});
+	// Let's wait until Playground is fully loaded
+	await client.isReady();
+</script>
+```
 
 :::info /remote.html is a special URL
 
@@ -38,9 +49,9 @@ API endpoint instead of the demo app with the browser UI. Read more about the di
 
 Now that you have a `client` object, you can use it to control the website inside the iframe. There are three ways to do that:
 
--   [Playground API Client](/developers/apis/javascript-api/playground-api-client)
--   [Blueprint JSON](/developers/apis/javascript-api/blueprint-json-in-api-client)
--   [Blueprint functions](/developers/apis/javascript-api/blueprint-functions-in-api-client)
+- [Playground API Client](/developers/apis/javascript-api/playground-api-client)
+- [Blueprint JSON](/developers/apis/javascript-api/blueprint-json-in-api-client)
+- [Blueprint functions](/developers/apis/javascript-api/blueprint-functions-in-api-client)
 
 ## Debugging and testing
 

diff --git a/packages/docs/site/docs/main/intro.md b/packages/docs/site/docs/main/intro.md
@@ -19,38 +19,38 @@ Playground is an online tool to experiment and learn about WordPress. This site
 
 <p class="docs-hubs">The WordPress Playground documentation is distributed across four separate hubs (subsites):</p>
 
--   👉 [**Documentation**](/) (you're here) – Introduction to WP Playground, starter guides and your entry point to WP Playground Docs.
--   [**Blueprints**](/blueprints) – Blueprints are JSON files for setting up your WordPress Playground instance. Learn about their possibilities from the Blueprints docs hub.
--   [**Developers**](/developers) – WordPress Playground was created as a programmable tool. Discover all the things you can do with it from your code in the Developers docs hub.
--   [**API Reference**](/api) – All the APIs exposed by WordPress Playground
+- 👉 [**Documentation**](/) (you're here) – Introduction to WP Playground, starter guides and your entry point to WP Playground Docs.
+- [**Blueprints**](/blueprints) – Blueprints are JSON files for setting up your WordPress Playground instance. Learn about their possibilities from the Blueprints docs hub.
+- [**Developers**](/developers) – WordPress Playground was created as a programmable tool. Discover all the things you can do with it from your code in the Developers docs hub.
+- [**API Reference**](/api) – All the APIs exposed by WordPress Playground
 
 ## Navigating this documentation hub
 
 This docs hub is focused on starting with WordPress Playground and is divided into the following major sections.
 
--   **[Quick Start Guide](/quick-start-guide)**: For those just starting out with WordPress Playground, this is where you can get up and running with WordPress Playground quickly to [start a new WordPress site](/quick-start-guide#start-a-new-wordpress-site) and [try a block/theme/plugin](/quick-start-guide#try-a-block-a-theme-or-a-plugin) or [test a specific WordPress/PHP version](/quick-start-guide#use-a-specific-wordpress-or-php-version).
+- **[Quick Start Guide](/quick-start-guide)**: For those just starting out with WordPress Playground, this is where you can get up and running with WordPress Playground quickly to [start a new WordPress site](/quick-start-guide#start-a-new-wordpress-site) and [try a block/theme/plugin](/quick-start-guide#try-a-block-a-theme-or-a-plugin) or [test a specific WordPress/PHP version](/quick-start-guide#use-a-specific-wordpress-or-php-version).
 
--   **[Playground web instance](/web-instance)**: Learn more about the Playground instance you get at https://playground.wordpress.net/
+- **[Playground web instance](/web-instance)**: Learn more about the Playground instance you get at https://playground.wordpress.net/
 
--   **[About Playground](/about)**: To learn about WordPress Playground, how safe it is, what you can do with and some of its current limitations, visit this section.
+- **[About Playground](/about)**: To learn about WordPress Playground, how safe it is, what you can do with and some of its current limitations, visit this section.
 
     Discover how you can leverage WordPress Playground to [Build](./about/build), [Test](./about/test), and [Launch](./about/launch) your products.
 
--   **[Guides](/guides)**: Explore our comprehensive guides to master new skills, find step-by-step instructions, and unlock valuable insights. Dive in to learn and grow!
+- **[Guides](/guides)**: Explore our comprehensive guides to master new skills, find step-by-step instructions, and unlock valuable insights. Dive in to learn and grow!
 
--   **[Contributing](/contributing)**: WordPress Playground is an open-source project that welcomes all contributors—from code to design, documentation to triage. Learn here how to contribute.
+- **[Contributing](/contributing)**: WordPress Playground is an open-source project that welcomes all contributors—from code to design, documentation to triage. Learn here how to contribute.
 
--   **[Links and resources](/resources)**: A nice compilation of useful links and resources related to WordPress Playground.
+- **[Links and resources](/resources)**: A nice compilation of useful links and resources related to WordPress Playground.
 
 ## First steps
 
 Whether you're a developer, a non-technical user, or a contributor, these docs will guide you as you start your learning journey:
 
--   [Start using WordPress Playground](/quick-start-guide) in 5 minutes (and check out the [demo site](https://playground.wordpress.net/))
--   [Get started for developing](/developers/build-your-first-app) with WordPress Playground
--   Use Playground as a zero-setup [local development environment](/developers/local-development/)
--   Read about the [limitations](/developers/limitations)
--   [WordCamp Contributor Day](/contributing/contributor-day)
+- [Start using WordPress Playground](/quick-start-guide) in 5 minutes (and check out the [demo site](https://playground.wordpress.net/))
+- [Get started for developing](/developers/build-your-first-app) with WordPress Playground
+- Use Playground as a zero-setup [local development environment](/developers/local-development/)
+- Read about the [limitations](/developers/limitations)
+- [WordCamp Contributor Day](/contributing/contributor-day)
 
 :::tip
 Read [**Introduction to Playground: running WordPress in the browser**](https://developer.wordpress.org/news/2024/04/05/introduction-to-playground-running-wordpress-in-the-browser/) blog post in the [WordPress Developer Blog](https://developer.wordpress.org/news) for a great introduction to WordPress Playground
@@ -60,19 +60,20 @@ Read [**Introduction to Playground: running WordPress in the browser**](https://
 
 If you're a developer or tech user, you may want to check directly the APIs available:
 
-import APIList from '@site/docs/\_fragments/\_api_list.mdx';
-
--   Read about [Playground APIs](/developers/apis/) and basic concepts
--   Review [links and resources](/resources)
--   Choose the right API for your app <APIList />
--   Dive into the [architecture](/developers/architecture) and learn how it all works
+- Read about [Playground APIs](/developers/apis/) and basic concepts
+- Review [links and resources](/resources)
+- Choose the right API for your app:
+    - [Query API](/developers/apis/query-api) enables basic operations using only query parameters
+    - [Blueprints API](/blueprints) gives you a great degree of control with a simple JSON file
+    - [JavaScript API](/developers/apis/javascript-api) gives you full control via a JavaScript client from an npm package
+- Dive into the [architecture](/developers/architecture) and learn how it all works
 
 ## Get Involved
 
 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!
 
--   See the [Contributors Handbook](/contributing) for all the details on how you can contribute.
--   Join us in the `#playground` channel in Slack (see the [WordPress Slack page](https://make.wordpress.org/chat/) for signup information)
+- See the [Contributors Handbook](/contributing) for all the details on how you can contribute.
+- Join us in the `#playground` channel in Slack (see the [WordPress Slack page](https://make.wordpress.org/chat/) for signup information)
 
 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/).
 

diff --git a/packages/docs/site/docs/main/quick-start-guide.md b/packages/docs/site/docs/main/quick-start-guide.md
@@ -4,8 +4,6 @@ slug: /quick-start-guide
 description: A 5-minute guide to get started with Playground. Learn how to test plugins, try themes, and use different WP/PHP versions.
 ---
 
-import ThisIsQueryApi from '@site/docs/\_fragments/\_this_is_query_api.md';
-
 # Start using WordPress Playground in 5 minutes
 
 WordPress Playground can help you with any of the following:
@@ -54,7 +52,7 @@ You can also mix and match these parameters and even add multiple plugins:
 
 https://playground.wordpress.net/?plugin=coblocks&plugin=friends&theme=pendant
 
-<ThisIsQueryApi />
+This is called [Query API](/developers/apis/query-api/) and you can learn more about it [here](/developers/apis/query-api/).
 
 ## Save your site
 
@@ -102,7 +100,7 @@ You can also use the `wp` and `php` [query parameters](/developers/apis/query-ap
 - https://playground.wordpress.net/?php=8.3
 - https://playground.wordpress.net/?php=8.2&wp=6.2
 
-<ThisIsQueryApi />
+This is called [Query API](/developers/apis/query-api/) and you can learn more about it [here](/developers/apis/query-api/).
 
 To learn more about preparing content for demos, see the [providing content for your demo guide](/guides/providing-content-for-your-demo).