diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c40bcca..36fa20a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,34 +1,33 @@ -## Contributing Guidelines +# Contribution Guidelines We encourage you to contribute your own Blueprints to this repository! -### Building your first Blueprint +## Build your first Blueprint -See the [Blueprints Crash Course](./docs/index.md). +Not sure how? Check out the [Blueprints 101](./docs/index.md). -### Submitting your Blueprint to this repository +## Submit your Blueprint to this repository -To keep the submission process smooth, please follow the following guidelines: +To keep the submission process smooth, please follow these guidelines: -Submit your Blueprint as a Pull Request to this repository. +1. Submit [a Pull Request (PR)](https://github.com/adamziel/blueprints/pulls) with your Blueprint. +2. The PR must contain a single `blueprint.json` file under the path `blueprints/your-blueprint-name/blueprint.json` (like [the examples here](https://github.com/adamziel/blueprints/tree/trunk/blueprints)). +3. Include all static files (WXR, ZIP, JPG, etc.) listed in the Blueprint in the submitted directory of your PR, and reference them via the `https://raw.githubusercontent.com` domain. +4. By submitting a Blueprint, you agree to license it under [GPLv2 or later license](https://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html). -Your Pull Request must contain a single `blueprint.json` file under a path `blueprints/your-blueprint-name/blueprint.json`. +## Blueprint metadata -All static files (WXR, ZIP, JPG etc.) referenced by the Blueprint must be included in the submitted directory in your Pull Request and referenced via the `raw.githubusercontent.com` domain. +Each Blueprint should include metadata within the top-level "meta" key of the `blueprint.json` file. -By submitting a Blueprint, you agree to license it under GPLv2 or later license. +Here's what's required: -### Blueprint Metadata +- **Title:** a clear and concise name for your Blueprint. +- **Author:** your GitHub username, to let others know who created the Blueprint. -Each Blueprint should include some basic metadata within the top-level "meta" key in the blueprint.json file. Here's what's required: +Optionally, you can add: -* Title: A clear and concise name for your Blueprint. -* Author (GitHub Username): Let others know who created the Blueprint. - -Optionally, you can also include: - -* Description: Provide a brief explanation of what your Blueprint offers. -* Categories: Specify relevant categories to help users find your Blueprint in the future Blueprints section on WordPress.org. +- **Description:** a brief explanation of what the Blueprint offers. +- **Categories:** specify relevant categories to help users find your Blueprint in the future Blueprints section on WordPress.org. Here's an example: @@ -43,6 +42,6 @@ Here's an example: } ``` -### Needing Help? +## Need help? -If you have questions or need assistance, start a new issue in this repository. +If you have questions or comments, [open a new issue](https://github.com/adamziel/blueprints/issues) in this repository. diff --git a/GALLERY.md b/GALLERY.md index c1df323..feb5601 100644 --- a/GALLERY.md +++ b/GALLERY.md @@ -1,6 +1,8 @@ # WordPress Blueprints Gallery -Here's the list of all the community Blueprints submitted to this repository. See the [contribution guidelines](./README.md#contributing-your-blueprint) to submit your Blueprint and share your WordPress setup with the world! +Here are all the community Blueprints submitted to this repository. + +Want to share your WordPress setup with the world? See the [contribution guidelines](./CONTRIBUTING.md) for more information on how to submit your Blueprint. | Title | Preview | Source | | ----- | ------- | ------ | diff --git a/README.md b/README.md index 942785a..6d89dd9 100644 --- a/README.md +++ b/README.md @@ -5,9 +5,11 @@ ## What are Blueprints? -Review the [Blueprints Crash Course](./docs/index.md) to get started. Here's a quick overview: +Check out [Blueprints 101](./docs/index.md) to get started. -Blueprints are WordPress setup descriptions that can be previewed live in [WordPress Playground](https://w.org/playground). Just like this one: +Here's a quick overview: + +Blueprints are WordPress setup scripts that you can preview live in [WordPress Playground](https://w.org/playground). Here's a simple example: ```json { @@ -19,33 +21,33 @@ Blueprints are WordPress setup descriptions that can be previewed live in [WordP [ 
 Preview in WordPress Playground 
 ](https://playground.wordpress.net/#%7B%22plugins%22:%5B%22hello-dolly%22,%22gutenberg%22%5D,%20%22login%22:%20true,%20%22landingPage%22:%20%22/wp-admin/plugins.php%22%20%7D) -Blueprints contain all the setup information including plugins, themes, site options, starter content to import, and more. +Blueprints contain all the installation instructions needed to setup WordPress, including plugins, themes, site options, starter content to import, and more. -Review the [Blueprints Crash Course](./docs/index.md) to get started with Blueprints. +Check out [Blueprints 101](./docs/index.md) to get started with Blueprints. ## Why use Blueprints? -Blueprints can help you: +Blueprints can help you -* Explore different setups – Try out different themes and plugins without the risk of breaking your site. It's a safe environment to see what works best for your needs. -* Save time – Instead of manually setting up your site, choosing themes, and installing plugins one by one, Blueprints do all that work for you in a few clicks. -* Learn WordPress – Blueprints are a fantastic way to play with a variety of WordPress configurations. +- **Explore different setups:** try out different themes and plugins without the risk of breaking your site. It's a safe environment to see what works best for your needs. +- **Save time**:** instead of manually setting up your site, choosing themes, and installing plugins one by one, Blueprints do all work for you. +- **Learn WordPress:** Blueprints are a fantastic way to play with a variety of WordPress configurations. ## Ready to jump in? -In this community space, you can: +This community space allows you to -* [Browse the Blueprints Gallery](./GALLERY.md) to explore a variety of WordPress sites. -* [Submit your own Blueprint](./CONTRIBUTING.md) to share your WordPress setup with the community. +* [Browse the Blueprints Gallery](./GALLERY.md) and explore diverse WordPress sites. +* [Submit your own Blueprint](./CONTRIBUTING.md) and share your WordPress setup with the community. ## Contributing your Blueprint -We encourage you to contribute your own Blueprints to this repository! New submissions are accepted as Pull Requests, for more details consult [Contributing Guidelines](./CONTRIBUTING.md) +We encourage you to contribute your Blueprints to this repository! We accepet new submissions as Pull Requests. Read the [Contributing Guidelines](./CONTRIBUTING.md) for more details. -## Needing Help? +## Need help? -If you have questions or need assistance, start a new issue in this repository. +If you have questions or comments, [open a new issue](https://github.com/adamziel/blueprints/issues) in this repository. -## Let's Build the Blueprint Community Together! +## Let's build the Blueprint Community together! -This is a minimal version 1 (v1) to get the community space up and running quickly. We plan to build upon this foundation based on your feedback. So, explore, create, and share your Blueprints! +This is a minimal version 1 (v1) to get the community space up and running. We plan to build upon this foundation, expand, and improve it—with your feedback. So, explore, create, and share your Blueprints! diff --git a/blueprints/grid-variations/blueprint.json b/blueprints/grid-variations/blueprint.json index 61a9e2b..9e5c9d6 100644 --- a/blueprints/grid-variations/blueprint.json +++ b/blueprints/grid-variations/blueprint.json @@ -2,8 +2,8 @@ "$schema": "https://playground.wordpress.net/blueprint-schema.json", "meta": { "title": "Grid Variations Experiments enabled", - "description": "Blueprint example to toggle on enable a feature from the Experiments page in Gutenberg plugin", "author": "bph", + "description": "Blueprint example to toggle on enable a feature from the Experiments page in Gutenberg plugin", "categories": ["Gutenberg", "Experiments"] }, "landingPage": "/wp-admin/site-editor.php", diff --git a/blueprints/latest-gutenberg/blueprint.json b/blueprints/latest-gutenberg/blueprint.json index cefb25d..46ecbcd 100644 --- a/blueprints/latest-gutenberg/blueprint.json +++ b/blueprints/latest-gutenberg/blueprint.json @@ -1,8 +1,8 @@ { "meta": { "title": "Latest Gutenberg plugin", - "description": "A preview of the latest version of the Gutenberg plugin.", "author": "zieladam", + "description": "A preview of the latest version of the Gutenberg plugin.", "categories": ["plugins"] }, "plugins": ["gutenberg"] diff --git a/docs/building-your-first-blueprint.md b/docs/build-your-first-blueprint.md similarity index 64% rename from docs/building-your-first-blueprint.md rename to docs/build-your-first-blueprint.md index 76484dc..ba8c35c 100644 --- a/docs/building-your-first-blueprint.md +++ b/docs/build-your-first-blueprint.md @@ -1,15 +1,15 @@ -## Building your first Blueprint +## Build your first Blueprint -Let's build a simple Blueprint that: +Let's build a simple Blueprint that 1. Creates a new WordPress site 2. Sets the site title to "My first Blueprint" -3. Sets the theme to Adventurer -4. Installs the Hello Dolly plugin from the WordPress plugin directory +3. Installs the _Adventurer_ theme +4. Installs the _Hello Dolly_ plugin from the WordPress plugin directory 5. Installs a custom plugin -6. Changing site content +6. Changes the site content -### Creating a new WordPress site +### 1. Create a new WordPress site Let's start by creating a `blueprint.json` file with the following contents: @@ -21,23 +21,24 @@ It may seem like nothing is happening, but this Blueprint already spins a WordPr [ 
Run Blueprint
 ](https://playground.wordpress.net/#{}) -#### Autocompletion +> [!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" +>} +>``` -If you use an IDE like VSCode or PHPStorm, use the Blueprint JSON Schema for an autocompleted Blueprint development experience. Simply 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 VSCode: +Here's what it looks like in VS Code: ![Autocompletion visualized](./assets/schema-autocompletion.png) -### Set the site title to "My first Blueprint" +### 2. Set the site title to "My first Blueprint" -Blueprints consist of a series of steps that define how to build a WordPress site. Before we write our first step, let's declare an empty list of steps: +Blueprints consist of a series of [steps]((https://wordpress.github.io/wordpress-playground/blueprints-api/steps)) that define how to build a WordPress site. Before you write the first step, declare an empty list of steps: ```json { @@ -46,9 +47,9 @@ Blueprints consist of a series of steps that define how to build a WordPress sit } ``` -This Blueprint isn't very exciting just yet – it effectively does same as the empty Blueprint above `{}`. We're about to change that! +This Blueprint isn't very exciting—it creates the same default site as the empty Blueprint above. Let's do something about it! -In WordPress, the site title is stored in the `blogname` option. Let's add our first step and set that option to "My first Blueprint": +WordPress stores the site title in the `blogname` option. Add your first step and set that option to "My first Blueprint": ```json { @@ -66,11 +67,11 @@ In WordPress, the site title is stored in the `blogname` option. Let's add our f [ 
Run Blueprint
 ](https://playground.wordpress.net/#https://playground.wordpress.net/#eyIkc2NoZW1hIjoiaHR0cHM6Ly9wbGF5Z3JvdW5kLndvcmRwcmVzcy5uZXQvYmx1ZXByaW50LXNjaGVtYS5qc29uIiwic3RlcHMiOlt7InN0ZXAiOiJzZXRTaXRlT3B0aW9ucyIsIm9wdGlvbnMiOnsiYmxvZ25hbWUiOiJNeSBmaXJzdCBCbHVlcHJpbnQifX1dfQ==) -The [setSiteOptions](https://wordpress.github.io/wordpress-playground/blueprints-api/steps#SetSiteOptionsStep) step sets the site options in the WordPress database. The `options` object contains the key-value pairs to set. In this case, we're setting the `blogname` option to "My first Blueprint". You can read more about this and other steps in the [Blueprint Steps API Reference](https://wordpress.github.io/wordpress-playground/blueprints-api/steps). +The [`setSiteOptions` step](https://wordpress.github.io/wordpress-playground/blueprints-api/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](https://wordpress.github.io/wordpress-playground/blueprints-api/steps). -#### Shorthands +### Shorthands -Some steps can be specified using a shorthand syntax for convenience. For example, the `setSiteOptions` step can be also written as: +You can specify some steps using a shorthand syntax. For example, you could write the `setSiteOptions` step like this: ```json { @@ -81,14 +82,11 @@ Some steps can be specified using a shorthand syntax for convenience. For exampl } ``` -The shorthand syntax and the step syntax are equivalent. Every step specified with the shorthand syntax is automatically added -at the beginning of the `steps` array in an arbitrary order. Shorthands are great for brevity, steps are great if you need more -control over the order of execution. +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. -### Setting the theme to Adventurer +### 3. Install the _Adventurer_ theme -Adventurer is an open-source source theme [available in the WordPress theme directory](https://wordpress.org/themes/adventurer/). -Let's install it on our site using the [installTheme](https://wordpress.github.io/wordpress-playground/blueprints-api/steps#InstallThemeStep) step: +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](https://wordpress.github.io/wordpress-playground/blueprints-api/steps#InstallThemeStep): ```json { @@ -109,21 +107,22 @@ Let's install it on our site using the [installTheme](https://wordpress.github.i [ 
Run Blueprint
 ](https://playground.wordpress.net/#eyIkc2NoZW1hIjoiaHR0cHM6Ly9wbGF5Z3JvdW5kLndvcmRwcmVzcy5uZXQvYmx1ZXByaW50LXNjaGVtYS5qc29uIiwib3B0aW9ucyI6eyJibG9nbmFtZSI6Ik15IGZpcnN0IEJsdWVwcmludCJ9LCJzdGVwcyI6W3sic3RlcCI6Imluc3RhbGxUaGVtZSIsInRoZW1lWmlwRmlsZSI6eyJyZXNvdXJjZSI6IndvcmRwcmVzcy5vcmcvdGhlbWVzIiwic2x1ZyI6ImFkdmVudHVyZXIifX1dfQ==) -The site now has the Adventurer theme installed and activated: +The site should now look like the screenshot below: ![Site with the adventurer theme](./assets/installed-adventurer-theme.png) -#### Resources +### Resources -The `themeZipFile` defines a [Resource](https://wordpress.github.io/wordpress-playground/blueprints-api/resources/) – a reference to an external file required for the step. There are different types of resources, such as `url`, `wordpress.org/themes`, `wordpress.org/plugins`, `vfs`, or `literal`. In this case, we're using the `wordpress.org/themes` resource to install the theme with the "Adventurer" slug from the WordPress theme directory: +The `themeZipFile` defines a [resource](https://wordpress.github.io/wordpress-playground/blueprints-api/resources/)—a reference to an external file required to complete the step. Playground supports different types of resources, including `url`, `wordpress.org/themes`, `wordpress.org/plugins`, `vfs`, or `literal`. The example uses the `wordpress.org/themes` resource, which requires a `slug` identical to the one used in WordPress theme directory: -https://wordpress.org/themes// -> https://wordpress.org/themes/adventurer/ +In this case, `https://wordpress.org/themes//` becomes `https://wordpress.org/themes/adventurer/`. -We'll use other resource types in the next steps, and you can learn more about resources in the [Blueprint Resources API Reference](https://wordpress.github.io/wordpress-playground/blueprints-api/resources/). +> [!NOTE] +> Learn more about the supported resources in the [Blueprint Resources API Reference](https://wordpress.github.io/wordpress-playground/blueprints-api/resources/). -### Installing the Hello Dolly plugin +### 4. Install the _Hello Dolly_ plugin -The Hello Dolly plugin is a classic WordPress plugin that displays a random lyric from the song "Hello, Dolly!" in the admin dashboard. Let's install it using the [installPlugin](https://wordpress.github.io/wordpress-playground/blueprints-api/steps#InstallPluginStep) step: +A classic WordPress plugin that displays random lyrics from the song "Hello, Dolly!" in the admin dashboard. Let's install it using the [`installPlugin` step](https://wordpress.github.io/wordpress-playground/blueprints-api/steps#InstallPluginStep): ```json { @@ -153,11 +152,11 @@ The Hello Dolly plugin is a classic WordPress plugin that displays a random lyri The Hello Dolly plugin is now installed and activated. -Similarly to the `themeZipFile`, the `pluginZipFile` defines a [Resource](https://wordpress.github.io/wordpress-playground/blueprints-api/resources/) – a reference to an external file required for the step. In this case, we're using the `wordpress.org/plugins` resource to install the plugin with the "hello-dolly" slug from the WordPress plugin directory. +Like the `themeZipFile`, the `pluginZipFile` defines a reference to an external file required for the step. The example uses the `wordpress.org/plugins` resource to install the plugin with the matching `slug` from the WordPress plugin directory. -### Installing a custom plugin +### 5. Install a custom plugin -Let's install our very own custom WordPress plugin taht adds a custom message to the admin dashboard. Here's the plugin code: +Let's install a custom WordPress plugin that adds a message to the admin dashboard: ```php  
Run Blueprint
 ](https://playground.wordpress.net/#eyJsb2dpbiI6dHJ1ZSwic2l0ZU9wdGlvbnMiOnsiYmxvZ25hbWUiOiJNeSBmaXJzdCBCbHVlcHJpbnQifSwic3RlcHMiOlt7InN0ZXAiOiJpbnN0YWxsVGhlbWUiLCJ0aGVtZVppcEZpbGUiOnsicmVzb3VyY2UiOiJ3b3JkcHJlc3Mub3JnL3RoZW1lcyIsInNsdWciOiJhZHZlbnR1cmVyIn19LHsic3RlcCI6Imluc3RhbGxQbHVnaW4iLCJwbHVnaW5aaXBGaWxlIjp7InJlc291cmNlIjoid29yZHByZXNzLm9yZy9wbHVnaW5zIiwic2x1ZyI6ImhlbGxvLWRvbGx5In19LHsic3RlcCI6Im1rZGlyIiwicGF0aCI6Ii93b3JkcHJlc3Mvd3AtY29udGVudC9wbHVnaW5zL2hlbGxvLW9uLXRoZS1kYXNoYm9hcmQifSx7InN0ZXAiOiJ3cml0ZUZpbGUiLCJwYXRoIjoiL3dvcmRwcmVzcy93cC1jb250ZW50L3BsdWdpbnMvaGVsbG8tb24tdGhlLWRhc2hib2FyZC9wbHVnaW4ucGhwIiwiZGF0YSI6Ijw/cGhwXG4vKlxuUGx1Z2luIE5hbWU6IFwiSGVsbG9cIiBvbiB0aGUgRGFzaGJvYXJkXG5EZXNjcmlwdGlvbjogQSBjdXN0b20gcGx1Z2luIHRvIHNob3djYXNlIFdvcmRQcmVzcyBCbHVlcHJpbnRzXG5WZXJzaW9uOiAxLjBcbkF1dGhvcjogV29yZFByZXNzIENvbnRyaWJ1dG9yc1xuKi9cblxuZnVuY3Rpb24gbXlfY3VzdG9tX3BsdWdpbigpIHtcbiAgICBlY2hvICc8aDE+SGVsbG8gZnJvbSBNeSBDdXN0b20gUGx1Z2luITwvaDE+Jztcbn1cblxuYWRkX2FjdGlvbignYWRtaW5fbm90aWNlcycsICdteV9jdXN0b21fcGx1Z2luJyk7In0seyJzdGVwIjoiYWN0aXZhdGVQbHVnaW4iLCJwbHVnaW5QYXRoIjoiaGVsbG8tb24tdGhlLWRhc2hib2FyZC9wbHVnaW4ucGhwIn1dfQ==) -The plugin is now installed and activated: +That's what it looks like when you navigate to the dashboard: ![Site with the custom plugin](./assets/installed-custom-plugin.png) -Encoding PHP files as JSON can be useful for quick testing, but it's quite inconvenient and difficult to read. Instead, let's create a ZIP file with our plugin code and use the [installPlugin](https://wordpress.github.io/wordpress-playground/blueprints-api/steps#InstallPluginStep) step to install it: +### Create a plugin and zip it + +Encoding PHP files as `JSON` can be useful for quick testing, but it's inconvenient and difficult to read. Instead, create a file with the plugin code, compress it, and use the `ZIP` file as the `resource` in the [`installPlugin` step](https://wordpress.github.io/wordpress-playground/blueprints-api/steps#InstallPluginStep) to install it (the path in the `URL` should match the one in your GitHub repository): ```json @@ -301,7 +300,7 @@ Encoding PHP files as JSON can be useful for quick testing, but it's quite incon } ``` -We can shorten that Blueprint even more using the shorthand syntax: +You can shorten that Blueprint even more using the shorthand syntax: ```json { @@ -328,13 +327,13 @@ We can shorten that Blueprint even more using the shorthand syntax: [ 
Run Blueprint
 ](https://playground.wordpress.net/#eyIkc2NoZW1hIjoiaHR0cHM6Ly9wbGF5Z3JvdW5kLndvcmRwcmVzcy5uZXQvYmx1ZXByaW50LXNjaGVtYS5qc29uIiwibG9naW4iOnRydWUsInNpdGVPcHRpb25zIjp7ImJsb2duYW1lIjoiTXkgZmlyc3QgQmx1ZXByaW50In0sInBsdWdpbnMiOlsiaGVsbG8tZG9sbHkiLCJodHRwczovL3Jhdy5naXRodWJ1c2VyY29udGVudC5jb20vYWRhbXppZWwvYmx1ZXByaW50cy90cnVuay9kb2NzL2hlbGxvLW9uLXRoZS1kYXNoYm9hcmQuemlwIl0sInN0ZXBzIjpbeyJzdGVwIjoiaW5zdGFsbFRoZW1lIiwidGhlbWVaaXBGaWxlIjp7InJlc291cmNlIjoid29yZHByZXNzLm9yZy90aGVtZXMiLCJzbHVnIjoiYWR2ZW50dXJlciJ9fV19) -### Changing site content +### 6. Change the site content -Finally, we'll delete the default content of the site and import a new one from a WordPress export file (WXR). +Finally, let's delete the default content of the site and import a new one from a WordPress export file (WXR). -#### Deleting the old content +### Delete the old content -There is no Blueprint step to delete the default content. We'll have to do it by running a snippet of custom PHP code: +There isn't a Blueprint step to delete the default content, but you can do that with a snippet of PHP code: ```php  
Run Blueprint
 ](https://playground.wordpress.net/#eyIkc2NoZW1hIjoiaHR0cHM6Ly9wbGF5Z3JvdW5kLndvcmRwcmVzcy5uZXQvYmx1ZXByaW50LXNjaGVtYS5qc29uIiwibG9naW4iOnRydWUsInNpdGVPcHRpb25zIjp7ImJsb2duYW1lIjoiTXkgZmlyc3QgQmx1ZXByaW50In0sInBsdWdpbnMiOlsiaGVsbG8tZG9sbHkiLCJodHRwczovL3Jhdy5naXRodWJ1c2VyY29udGVudC5jb20vYWRhbXppZWwvYmx1ZXByaW50cy90cnVuay9kb2NzL2Fzc2V0cy9oZWxsby1mcm9tLXRoZS1kYXNoYm9hcmQuemlwIl0sInN0ZXBzIjpbeyJzdGVwIjoiaW5zdGFsbFRoZW1lIiwidGhlbWVaaXBGaWxlIjp7InJlc291cmNlIjoid29yZHByZXNzLm9yZy90aGVtZXMiLCJzbHVnIjoiYWR2ZW50dXJlciJ9fSx7InN0ZXAiOiJydW5QSFAiLCJjb2RlIjoiPD9waHBcbnJlcXVpcmUgJy93b3JkcHJlc3Mvd3AtbG9hZC5waHAnO1xuXG4kcG9zdHMgPSBnZXRfcG9zdHMoYXJyYXkoXG4gICAgJ251bWJlcnBvc3RzJyA9PiAtMSxcbiAgICAncG9zdF90eXBlJyA9PiBhcnJheSgncG9zdCcsICdwYWdlJyksXG4gICAgJ3Bvc3Rfc3RhdHVzJyA9PiAnYW55J1xuKSk7XG5cbmZvcmVhY2ggKCRwb3N0cyBhcyAkcG9zdCkge1xuICAgIHdwX2RlbGV0ZV9wb3N0KCRwb3N0LT5JRCwgdHJ1ZSk7XG59In0seyJzdGVwIjoiaW1wb3J0V3hyIiwiZmlsZSI6eyJyZXNvdXJjZSI6InVybCIsInVybCI6Imh0dHBzOi8vcmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbS9Xb3JkUHJlc3MvdGhlbWUtdGVzdC1kYXRhL21hc3Rlci90aGVtZXVuaXR0ZXN0ZGF0YS53b3JkcHJlc3MueG1sIn19XX0=) -And... that's it! - -### Next steps +And that's it. Congratulations on creating your first Blueprint! 🥳 +*** +**Table of contents** +1. [What are Blueprints, and what can you do with them?](./what-are-blueprints-what-you-can-do-with-them.md) +2. [How to load and run Blueprints?](./how-to-load-run-blueprints.md) +3. Build your first Blueprint +4. [Troubleshoot and debug Blueprints](./troubleshoot-debug-blueprints.md) diff --git a/docs/debugging-blueprints.md b/docs/debugging-blueprints.md deleted file mode 100644 index 6cb98b4..0000000 --- a/docs/debugging-blueprints.md +++ /dev/null @@ -1,61 +0,0 @@ -## More Resources - -When building Blueprints, you might run into issues. Here are some tips to help you debug them: - -### Review Common gotchas - -* Require wp-load: to run a WordPress PHP function using the runPHP step, you’d need to require [wp-load.php](https://github.com/WordPress/WordPress/blob/master/wp-load.php). So, the value of the code key should start with " Preferences > Advanced and checking "Show Develop menu in menu bar." -2. Then press `Cmd + Option + I` to open the Web Inspector. - -You can learn more by visiting the [Safari Developer Tools Guide](https://developer.apple.com/documentation/web_inspector). - -#### Microsoft Edge - -To open the developer tools in Edge: - -1. Press `F12` or `Ctrl + Shift + I` on Windows. -2. Alternatively, click on the menu (three dots in the upper right corner), select "More tools," and then "Developer tools." - -For further information, refer to the [Microsoft Edge DevTools documentation](https://learn.microsoft.com/en-us/microsoft-edge/devtools-guide-chromium/). - -By using these developer tools, you can inspect network requests, view console logs, debug JavaScript, and examine the DOM and CSS styles applied to your webpage. This can be invaluable in diagnosing and fixing issues with your Blueprint. - -### Ask for help - -The community is here to help you! If you have questions or need assistance, start a new issue in this repository and we’ll do our best to help you out. Remember to include: - -* The Blueprint you’re trying to run. -* The error message you’re seeing, if any. -* The full output from the browser developer tools. -* Any other relevant information that might help us understand the issue. - diff --git a/docs/developer-tools.md b/docs/developer-tools.md deleted file mode 100644 index ef9acdd..0000000 --- a/docs/developer-tools.md +++ /dev/null @@ -1,18 +0,0 @@ -## Developer Tools - -### JSON Schema - -If you use an IDE like VSCode or PHPStorm, use the Blueprint JSON Schema for an autocompleted Blueprint development experience. Simply add the following line at the top of your blueprint.json file: - -```json -{ - "$schema": "https://playground.wordpress.net/blueprint-schema.json" -} -``` - -### Blueprints Builder - -You use this in-browser Blueprints editor to build, validate, and preview your Blueprints in the browser. Note the editor is under development and the embedded Playground sometimes won't load – in these cases you'll need to refresh the page. We are aware of these shortcomings and are working to improve the experience. - -[https://playground.wordpress.net/builder/builder.html](https://playground.wordpress.net/builder/builder.html) - diff --git a/docs/how-to-load-run-blueprints.md b/docs/how-to-load-run-blueprints.md new file mode 100644 index 0000000..bd69da7 --- /dev/null +++ b/docs/how-to-load-run-blueprints.md @@ -0,0 +1,49 @@ +# How to load and run Blueprints + +## URL fragment + +The easiest way to start using 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 the 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**](./build-your-first-blueprint.md). + +### 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/adamziel/blueprints/trunk/blueprints/latest-gutenberg/blueprint.json](https://playground.wordpress.net/?blueprint-url=https://raw.githubusercontent.com/adamziel/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: * +``` + +*** + +**Table of contents** +1. [What are Blueprints, and what can you do with them?](./what-are-blueprints-what-you-can-do-with-them.md) +2. How to load and run Blueprints? +3. [Build your first Blueprint](./build-your-first-blueprint.md) +4. [Troubleshoot and debug Blueprints](./troubleshoot-debug-blueprints.md) diff --git a/docs/how-to-run-blueprints.md b/docs/how-to-run-blueprints.md deleted file mode 100644 index 743ef94..0000000 --- a/docs/how-to-run-blueprints.md +++ /dev/null @@ -1,46 +0,0 @@ -## How to Run Blueprints - -### URL Fragment - -The easiest way to start using Blueprints is to paste one into the URL "fragment" on the WordPress Playground website. - -For example, to create a Playground with specific versions of WordPress and PHP you would use the following Blueprint: - -```json -{ - "$schema": "https://playground.wordpress.net/blueprint-schema.json", - "preferredVersions": { - "php": "7.4", - "wp": "5.9" - } -} -``` - -And then you would go to `https://playground.wordpress.net/#{"preferredVersions": {"php":"7.4", "wp":"5.9"}}` – you can also use the "Run the Blueprint" button below to do the same: - -[ 
Run the Blueprint
 ](https://playground.wordpress.net/#{"preferredVersions":{"php":"7.4","wp":"5.9"}}) - -#### Base64 Encoded Blueprints - -Some tools, including GitHub, might not format the Blueprint correctly when pasted into the URL. In such cases, you can encode your Blueprint in Base64 and append it to the URL. For example, here's the above Blueprint in the Base64 format: - -``` -eyJwcmVmZXJyZWRWZXJzaW9ucyI6IHsicGhwIjoiNy40IiwgIndwIjoiNS45In19 -``` - -And you could run it by going to - -[https://playground.wordpress.net/#eyJwcmVmZXJyZWRWZXJzaW9ucyI6IHsicGhwIjoiNy40IiwgIndwIjoiNS45In19](https://playground.wordpress.net/#eyJwcmVmZXJyZWRWZXJzaW9ucyI6IHsicGhwIjoiNy40IiwgIndwIjoiNS45In19) - -### Load Blueprint from a URL - -When your Blueprint gets too wieldy, you load it via the `?blueprint-url` query parameter in the URL, like this: - -[https://playground.wordpress.net/?blueprint-url=https://raw.githubusercontent.com/adamziel/blueprints/trunk/blueprints/latest-gutenberg/blueprint.json](https://playground.wordpress.net/?blueprint-url=https://raw.githubusercontent.com/adamziel/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/docs/index.md b/docs/index.md index 68d4ad1..822b1b5 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,13 +1,14 @@ -## Blueprints Crash Course +# Blueprints 101 -Welcome to the Blueprints documentation! Here you will find everything you need to know about Blueprints, including what they are, how to create them, and how to use them effectively. +Welcome to a Blueprints crash course, where you'll find everything you need to know about Blueprints: what they are, how to create them, and how to use them effectively. -This page is your entrypoint to the awesome: - -1. [What are Blueprints and how are they useful?](./what-are-blueprints.md) -2. [How to run Blueprints?](./how-to-run-blueprints.md) -3. [Building your first Blueprint](./building-your-first-blueprint.md) -4. [Debugging Blueprints](./debugging-blueprints.md) -5. [Developer Tools](./developer-tools.md) -6. [More Resources](./more-resources.md) +1. [What are Blueprints, and what can you do with them?](./what-are-blueprints-what-you-can-do-with-them.md) +2. [How to load and run Blueprints?](./how-to-load-run-blueprints.md) +3. [Build your first Blueprint](./build-your-first-blueprint.md) +4. [Troubleshoot and debug Blueprints](./troubleshoot-debug-blueprints.md) +> [!NOTE] +> ## Blueprints version 2 +> The team is exploring ways to transition Blueprints from a TypeScript library to a PHP library. This would allow people to run Blueprints in any WordPress environments: Playground, a hosted site, or a local setup. +> +> The proposed [new specification](https://github.com/WordPress/blueprints/issues/6) is discussed on a separate [GitHub repository](https://github.com/WordPress/blueprints/), and you’re more than welcome to join (there or on the [#meta-playground](https://wordpress.slack.com/archives/C04EWKGDJ0K) Slack channel) and help shape the next generation of Playground. diff --git a/docs/more-resources.md b/docs/more-resources.md deleted file mode 100644 index 92f8482..0000000 --- a/docs/more-resources.md +++ /dev/null @@ -1,15 +0,0 @@ -## More Resources - -Here are some additional resources to help you learn more about working with Blueprints: - -* [Introduction to WordPress Playground](https://developer.wordpress.org/news/?p=3309&preview=1&_ppp=6161ec285a) -* [Blueprint Resources reference](https://wordpress.github.io/wordpress-playground/blueprints-api/resources) -* [Blueprints Steps reference](https://wordpress.github.io/wordpress-playground/blueprints-api/steps) -* [Blueprints examples](https://wordpress.github.io/wordpress-playground/blueprints-api/examples) -* [Various demos and apps built with Blueprints](https://wordpress.github.io/wordpress-playground/links-and-resources#apps-built-with-wordpress-playground) - -### Blueprints version 2 - -The team is exploring ways to transition Blueprints from a TypeScript library to a PHP library to enable running them in all WordPress environments – whether they're Playground, a hosted site, or your local setup. - -The proposed [new specification](https://github.com/WordPress/blueprints/issues/6) is discussed on a separate [GitHub repository](https://github.com/WordPress/blueprints/), and you’re more than welcome to join (there or on the [#meta-playground](https://wordpress.slack.com/archives/C04EWKGDJ0K) Slack channel) and help shape the next generation of Playground. diff --git a/docs/troubleshoot-debug-blueprints.md b/docs/troubleshoot-debug-blueprints.md new file mode 100644 index 0000000..c9d7da7 --- /dev/null +++ b/docs/troubleshoot-debug-blueprints.md @@ -0,0 +1,43 @@ +# Troubleshoot and debug Blueprints + +When you build Blueprints, you might run into issues. Here are tips and tools to help you debug them: + +## Review Common gotchas + +- Require `wp-load`: to run a WordPress PHP function using the `runPHP` step, you’d need to require [wp-load.php](https://github.com/WordPress/WordPress/blob/master/wp-load.php). So, the value of the `code` key should start with `" [!CAUTION] +> The editor is under development and the embedded Playground sometimes fails to load. To get around it, refresh the page. We're aware of that, and are working to improve the experience. + +## Check for erros in the browser console + +If your Blueprint isn’t running as expected, open the browser developer tools to see if there are any errors. + +To open the developer tools in Chrome, Firefox, Safari*, and Edge: press `Ctrl + Shift + I` on Windows/Linux or `Cmd + Option + I` on macOS. + +> [!WARNING] +> If you haven't yet, enable the Develop menu: go to **Safari > Settings... > Advanced** and check **Show features for web developers**. + +The developer tools window allows you to inspect network requests, view console logs, debug JavaScript, and examine the DOM and CSS styles applied to your webpage. This is crucial for diagnosing and fixing issues with Blueprints. + +## Ask for help + +The community is here to help! If you have questions or comments, [open a new issue](https://github.com/adamziel/blueprints/issues) in this repository. Remember to include the following details: + +- The Blueprint you’re trying to run. +- The error message you’re seeing, if any. +- The full output from the browser developer tools. +- Any other relevant information that might help us understand the issue: OS, broswer version, etc. + +*** + +**Table of contents** +1. [What are Blueprints, and what can you do with them?](./what-are-blueprints-what-you-can-do-with-them.md) +2. [How to load and run Blueprints?](./how-to-load-run-blueprints.md) +3. [Build your first Blueprint](./build-your-first-blueprint.md) +4. Troubleshoot and debug Blueprints diff --git a/docs/what-are-blueprints-what-you-can-do-with-them.md b/docs/what-are-blueprints-what-you-can-do-with-them.md new file mode 100644 index 0000000..116792a --- /dev/null +++ b/docs/what-are-blueprints-what-you-can-do-with-them.md @@ -0,0 +1,57 @@ +# What are Blueprints, and what can you do with them? + +Blueprints are `JSON` files that you can use to 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 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"], + "themes": ["twentynineteen"], + "settings": { + "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: + +- **Flexibility**: developers can make surgical 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 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 up once. +- **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 out 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. + +> [!NOTE] +> **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](https://wordpress.github.io/wordpress-playground/blueprints-api/examples) +> - [Demos and apps built with Blueprints](https://wordpress.github.io/wordpress-playground/links-and-resources#apps-built-with-wordpress-playground) + +*** + +**Table of contents** +1. What are Blueprints, and what can you do with them? +2. [How to load and run Blueprints?](./how-to-load-run-blueprints.md) +3. [Build your first Blueprint](./build-your-first-blueprint.md) +4. [Troubleshoot and debug Blueprints](./troubleshoot-debug-blueprints.md) diff --git a/docs/what-are-blueprints.md b/docs/what-are-blueprints.md deleted file mode 100644 index c368c9f..0000000 --- a/docs/what-are-blueprints.md +++ /dev/null @@ -1,46 +0,0 @@ -## What are Blueprints and how are they useful? - -Blueprints are JSON files you can use to create a whole website, including plugins, themes, content (posts, pages, taxonomy, and comments), settings (site name, users, permalinks, and more), etc. You can generate a WooCommerce store complete with products, a magazine populated with articles, a corporate blog with multiple users, and more. - -Blueprints support advanced use cases, like file system and database manipulation, and gives 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 Blueprint example - -A Blueprint might look something like this: - -```json -{ - "plugins": ["akismet", "gutenberg"], - "themes": ["twentynineteen"], - "settings": { - "blogname": "My Blog", - "blogdescription": "Just another WordPress site" - }, - "constants": { - "WP_DEBUG": true - } -} -``` - -In this example, the Blueprint installs the Akismet and Gutenberg plugins, the Twenty Nineteen theme, and sets the site name and description. It also enables debugging mode. - -### Blueprints Strengths - -Blueprints are an invaluable tool for building WordPress sites: - -* **Flexibility** – With Blueprints, developers can make surgical adjustments to the build process. -* **Consistency**: Blueprints ensure that every new site starts with the same configuration. -* **Lightweight** – Blueprints are tiny text files that cost almost nothing to store or transfer. -* **Transparency** – A Blueprint includes all the commands needed to build a WordPress Snapshot. You can read through it and understand exactly how the site is built. -* **Time Efficiency**: By using Blueprints, the time-consuming process of manually setting up a new WordPress site is significantly reduced. Instead of going through the steps of installing and configuring themes and plugins for each new project, a Blueprint can be applied to set everything up. -* **Up-to-date dependencies** – A typical Blueprint fetches the latest version of WordPress, a particular plugin, and, perhaps, a theme. The resulting Snapshot is then up to date with the latest features and security fixes. -4. **Collaboration and Sharing**: Blueprints easy to diff and review in tools like GitHub and can be shared within a team or with the WordPress community, allowing others to benefit from a 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 out various setups without the risk of breaking a live site. -* **WordPress.org integration** – Writing a Blueprint enables you to demo your plugin in the WordPress plugin directory. -* **Spinning a development environment** – A new developer in the team could just download the Blueprint, run a hypothetical wp up command, and get a fresh dev env. The CI scripts could reuse the same method, and even the production build could be based on a Blueprint. - -### Blueprints Use Cases - -* Developers can add a Preview button to their [plugin](https://developer.wordpress.org/plugins/wordpress-org/previews-and-blueprints/) submissions or [Theme Trac tickets](https://meta.trac.wordpress.org/ticket/7382) -* Check out [the Blueprints examples](https://wordpress.github.io/wordpress-playground/blueprints-api/examples) and [the various demos and apps](https://wordpress.github.io/wordpress-playground/links-and-resources#apps-built-with-wordpress-playground) in the docs to learn more about the (endless) possibilities of Blueprints. -* Embed a pre-configured WordPress site in your website using the [WordPress Playground Block](https://wordpress.org/plugins/interactive-code-block/).