The WordPress Playground documentation is distributed across four separate hubs (subsites):
+ +- [**Documentation**](/) – Introduction to WP Playground, starter guides and your entry point to WP Playground Docs. +- 👉 [**Blueprints**](/blueprints) (you're here) – Blueprints are JSON files for setting up your WordPress Playground instance. Learn about their possibilities from this 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 the Blueprints documentation hub + +This docs hub is focused on Blueprints info and is divided into the following major sections: + +- [Getting started with Blueprints](/blueprints/getting-started): Quick Start Guide to setting up a WordPress Playground instance using Blueprint JSON files. + +- [Tutorial - Blueprints 101](/blueprints/tutorial) - Blueprints API crash course. The tutorial will guide you through the complete process of creating a blueprint that loads a theme and plugin (among other things). + +- [Blueprint data Format](/blueprints/data-format): Blueprint JSON files define your Playground instance with various properties. This section highlights the key properties you need to know. + +- [Using Blueprints](/blueprints/using-blueprints): Learn in this section different ways to use Blueprints. + +- [Steps](/blueprints/steps): API Reference of all the available steps that can be set in a blueprint to run tasks such as login, plugin/theme activation, file operations, and more. + +- [Blueprint Bundles](/blueprints/bundles): Learn how to create and use Blueprint bundles - self-contained packages that include a Blueprint and all its resources. + +- [Examples](/blueprints/examples): Compilation of Blueprint examples for various WordPress Playground setups, including installing themes/plugins, running PHP code, enabling features, and loading specific WordPress versions. + +- [Troubleshoot and debug Blueprints](/blueprints/troubleshoot-and-debug): Tips and tools for troubleshooting and debugging Blueprints. diff --git a/packages/docs/site/i18n/tl/docusaurus-plugin-content-docs/current/blueprints/tutorial/01-what-are-blueprints-what-you-can-do-with-them.md b/packages/docs/site/i18n/tl/docusaurus-plugin-content-docs/current/blueprints/tutorial/01-what-are-blueprints-what-you-can-do-with-them.md new file mode 100644 index 0000000000..212cbab1d1 --- /dev/null +++ b/packages/docs/site/i18n/tl/docusaurus-plugin-content-docs/current/blueprints/tutorial/01-what-are-blueprints-what-you-can-do-with-them.md @@ -0,0 +1,66 @@ +--- +title: What are Blueprints? +slug: /blueprints/tutorial/what-are-blueprints-what-you-can-do-with-them +description: Getting started with Blueprints +--- + +# What are Blueprints, and what can you do with them? + +With WordPress Playground you can create a whole website, including plugins, themes, content (posts, pages, taxonomy, and comments), settings (site name, users, permalinks, and more), etc. They allow you to generate a WooCommerce store complete with products, a magazine populated with articles, a corporate blog with multiple users, and more. + +Blueprints are `JSON` files that you can use to configure Playground instances. + +Blueprints support advanced use cases, like file system and database manipulation, and give you fine-grained control over the instance you create. The WordPress Test Team has been using Playground in [the 6.5 beta release cycle](https://wordpress.org/news/2024/03/wordpress-6-5-release-candidate-2/), creating a Blueprint that loads the latest version, several testing plugins, and dummy data. + +## A simple example + +A Blueprint might look something like this: + +```json +{ + "plugins": ["akismet", "gutenberg"], + "steps": [ + { + "step": "installTheme", + "themeData": { + "resource": "wordpress.org/themes", + "slug": "twentynineteen" + } + } + ], + "siteOptions": { + "blogname": "My Blog", + "blogdescription": "Just another WordPress site" + }, + "constants": { + "WP_DEBUG": true + } +} +``` + +The Blueprint above installs the _Akismet_ and _Gutenberg_ plugins and the _Twenty Nineteen_ theme, sets the site name and description, and enables the WordPress debugging mode. + +## The benefits of Blueprints + +Blueprints are an invaluable tool for building WordPress sites via Playground + +- **Flexibility**: developers can make granular adjustments to the build process. +- **Consistency**: ensure that every new site starts with the same configuration. +- **Lightweight**: small text files that are easy to store and transfer. +- **Transparency**: A Blueprint includes all the commands needed to build a snapshot of a WordPress site. You can read through it and understand how the site is built. +- **Productivity**: reduces the time-consuming process of manually setting up a new WordPress site. Instead of installing and configuring themes and plugins for each new project, apply a Blueprint and set everything in one process. +- **Up-to-date dependencies**: fetch the latest version of WordPress, a particular plugin, or a theme. Your snapshot is always up to date with the latest features and security fixes. +- **Collaboration**: the `JSON` files are easy to review in tools like GitHub. Share Blueprints with your team or the WordPress community. Allowing others to use your well-configured setup. +- **Experimentation and Learning**: For those new to WordPress or looking to experiment with different configurations, Blueprints provide a safe and easy way to try new setups without "breaking" a live site. +- **WordPress.org integration**: offer a [demo of your plugin](https://developer.wordpress.org/plugins/wordpress-org/previews-and-blueprints/) in the WordPress plugin directory, or a preview in a [Theme Trac ticket](https://meta.trac.wordpress.org/ticket/7382). +- **Spinning a development environment**: A new developer in the team could download the Blueprint, run a hypothetical `wp up` command, and get a fresh developer environments—loaded with everything they need. The entire CI/CD process can reuse the same Blueprint. + +:::info **More Resources** +Visit these links to learn more about the (endless) possibilities of Blueprints: + +- [Introduction to WordPress Playground](https://developer.wordpress.org/news/2024/04/05/introduction-to-playground-running-wordpress-in-the-browser/) +- Embed a pre-configured WordPress site in your website using the [WordPress Playground Block](https://wordpress.org/plugins/interactive-code-block/). +- [Blueprints examples](/blueprints/examples) +- [Demos and apps built with Blueprints](/resources#apps-built-with-wordpress-playground) + +::: diff --git a/packages/docs/site/i18n/tl/docusaurus-plugin-content-docs/current/blueprints/tutorial/02-how-to-load-run-blueprints.md b/packages/docs/site/i18n/tl/docusaurus-plugin-content-docs/current/blueprints/tutorial/02-how-to-load-run-blueprints.md new file mode 100644 index 0000000000..5db5233b55 --- /dev/null +++ b/packages/docs/site/i18n/tl/docusaurus-plugin-content-docs/current/blueprints/tutorial/02-how-to-load-run-blueprints.md @@ -0,0 +1,47 @@ +--- +title: How to run Blueprints +slug: /blueprints/tutorial/how-to-load-run-blueprints +description: Learn about the multiple ways to use blueprints +--- + +# How to load and run Blueprints + +## URL fragment + +The fastest way to run Blueprints is to paste one into the URL "fragment" of a WordPress Playground website. Just add a `#` after the `.net/`. + +Let's say you want to create a Playground with specific versions of WordPress and PHP using the following Blueprint: + +```json +{ + "$schema": "https://playground.wordpress.net/blueprint-schema.json", + "preferredVersions": { + "php": "7.4", + "wp": "5.9" + } +} +``` + +To run it, go to `https://playground.wordpress.net/#{"preferredVersions": {"php":"7.4", "wp":"5.9"}}`. You can also use the button below: + +[ Run Blueprint ](https://playground.wordpress.net/#{"preferredVersions":{"php":"7.4","wp":"5.9"}}) + +Use this method to run the example code in the next chapter, [**Build your first Blueprint**](/blueprints/tutorial/build-your-first-blueprint). + +### Base64 encoded Blueprints + +Some tools, including GitHub, might not format the Blueprint correctly when pasted into the URL. In such cases, [encode your Blueprint in Base64](https://www.base64encode.org) and append it to the URL. For example, that's the above Blueprint in Base64 format: `eyJwcmVmZXJyZWRWZXJzaW9ucyI6IHsicGhwIjoiNy40IiwgIndwIjoiNS45In19`. + +To run it, go to [https://playground.wordpress.net/#eyJwcmVmZXJyZWRWZXJzaW9ucyI6IHsicGhwIjoiNy40IiwgIndwIjoiNS45In19](https://playground.wordpress.net/#eyJwcmVmZXJyZWRWZXJzaW9ucyI6IHsicGhwIjoiNy40IiwgIndwIjoiNS45In19) + +### Load Blueprint from a URL + +When your Blueprint gets too wieldy, you can load it via the `?blueprint-url` query parameter in the URL, like this: + +[https://playground.wordpress.net/?blueprint-url=https://raw.githubusercontent.com/wordpress/blueprints/trunk/blueprints/latest-gutenberg/blueprint.json](https://playground.wordpress.net/?blueprint-url=https://raw.githubusercontent.com/wordpress/blueprints/trunk/blueprints/latest-gutenberg/blueprint.json) + +Note that the Blueprint must be publicly accessible and served with [the correct `Access-Control-Allow-Origin` header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Origin): + +``` +Access-Control-Allow-Origin: * +``` diff --git a/packages/docs/site/i18n/tl/docusaurus-plugin-content-docs/current/blueprints/tutorial/03-build-your-first-blueprint.md b/packages/docs/site/i18n/tl/docusaurus-plugin-content-docs/current/blueprints/tutorial/03-build-your-first-blueprint.md new file mode 100644 index 0000000000..8e0473ea2a --- /dev/null +++ b/packages/docs/site/i18n/tl/docusaurus-plugin-content-docs/current/blueprints/tutorial/03-build-your-first-blueprint.md @@ -0,0 +1,417 @@ +--- +title: Build your first Blueprint +slug: /blueprints/tutorial/build-your-first-blueprint +description: Six steps to your first blueprint +--- + +Let's build an elementary Blueprint that + +1. Creates a new WordPress site +2. Sets the site title to "My first Blueprint" +3. Installs the _Adventurer_ theme +4. Installs the _Hello Dolly_ plugin from the WordPress plugin directory +5. Installs a custom plugin +6. Changes the site content + +## 1. Create a new WordPress site + +Let's start by creating a `blueprint.json` file with the following contents: + +```json +{} +``` + +It may seem like nothing is happening, but this Blueprint already spins up a WordPress site with the latest major version. + +[ Run Blueprint ](https://playground.wordpress.net/#{}) + +:::tip **Autocomplete** + +If you use an IDE, like VS Code or PHPStorm, you can use the [Blueprint JSON Schema](https://playground.wordpress.net/blueprint-schema.json) for an autocompleted Blueprint development experience. Add the following line at the top of your `blueprint.json` file: + +```json +{ + "$schema": "https://playground.wordpress.net/blueprint-schema.json" +} +``` + +::: +Here's what it looks like in VS Code: + + + +## 2. Set the site title to "My first Blueprint" + +Blueprints consist of a series of [steps](/blueprints/steps) that define how to build a WordPress site. Before you write the first step, declare an empty list of steps: + +```json +{ + "$schema": "https://playground.wordpress.net/blueprint-schema.json", + "steps": [] +} +``` + +This Blueprint isn't very exciting—it creates the same default site as the empty Blueprint above. Let's do something about it! + +WordPress stores the site title in the `blogname` option. Add your first step and set that option to "My first Blueprint": + +```json +{ + "$schema": "https://playground.wordpress.net/blueprint-schema.json", + "steps": [ + { + "step": "setSiteOptions", + "options": { + "blogname": "My first Blueprint" + } + } + ] +} +``` + +[ Run Blueprint ](https://playground.wordpress.net/#https://playground.wordpress.net/#eyIkc2NoZW1hIjoiaHR0cHM6Ly9wbGF5Z3JvdW5kLndvcmRwcmVzcy5uZXQvYmx1ZXByaW50LXNjaGVtYS5qc29uIiwic3RlcHMiOlt7InN0ZXAiOiJzZXRTaXRlT3B0aW9ucyIsIm9wdGlvbnMiOnsiYmxvZ25hbWUiOiJNeSBmaXJzdCBCbHVlcHJpbnQifX1dfQ==) + +The [`setSiteOptions` step](/blueprints/steps#SetSiteOptionsStep) specifies the site options in the WordPress database. The `options` object contains the key-value pairs to set. In this case, you changed the value of the `blogname` key to "My first Blueprint". You can read more about all available steps in the [Blueprint Steps API Reference](/blueprints/steps). + +### Shorthands + +You can specify some steps using a shorthand syntax. For example, you could write the `setSiteOptions` step like this: + +```json +{ + "$schema": "https://playground.wordpress.net/blueprint-schema.json", + "siteOptions": { + "blogname": "My first Blueprint" + } +} +``` + +The shorthand syntax and the step syntax correspond with each other. Every step specified with the shorthand syntax is automatically added at the beginning of the `steps` array in an arbitrary order. Which should you choose? Use shorthands when brevity is your main concern, use steps when you need more control over the order of execution. + +## 3. Install the _Adventurer_ theme + +Adventurer is an open-source theme [available in the WordPress theme directory](https://wordpress.org/themes/adventurer/). Let's install it using the [`installTheme` step](/blueprints/steps#InstallThemeStep): + +```json +{ + "siteOptions": { + "blogname": "My first Blueprint" + }, + "steps": [ + { + "step": "installTheme", + "themeData": { + "resource": "wordpress.org/themes", + "slug": "adventurer" + } + } + ] +} +``` + +[ Run Blueprint ](https://playground.wordpress.net/#eyIkc2NoZW1hIjoiaHR0cHM6Ly9wbGF5Z3JvdW5kLndvcmRwcmVzcy5uZXQvYmx1ZXByaW50LXNjaGVtYS5qc29uIiwib3B0aW9ucyI6eyJibG9nbmFtZSI6Ik15IGZpcnN0IEJsdWVwcmludCJ9LCJzdGVwcyI6W3sic3RlcCI6Imluc3RhbGxUaGVtZSIsInRoZW1lWmlwRmlsZSI6eyJyZXNvdXJjZSI6IndvcmRwcmVzcy5vcmcvdGhlbWVzIiwic2x1ZyI6ImFkdmVudHVyZXIifX1dfQ==) + +The site should now look like the screenshot below: + + + +### Resources + +The `themeData` defines a [resource](/blueprints/steps/resources) and referrences an external file required to complete the step. Playground supports different types of resources, including + +- `url`, +- `wordpress.org/themes`, +- `wordpress.org/plugins`, +- `vfs`(virtual file system), or +- `literal`. + +The example uses the `wordpress.org/themes` resource, which requires a `slug` identical to the one used in WordPress theme directory: + +In this case, `https://wordpress.org/themes/