Docs: Move Steps Shorthands to a separate page to fix Steps TOC (#1265)

Moves the Steps Shorthands documentation, merged in #1261, to a separate page. ## What problem is it solving? @ironnysh [noted](#1261 (comment)) that merging the PR messed up the table of contents on the steps page: <img width="512" alt="323169294-76cb6e7b-2ec5-4f66-b6b6-04e0dbcd1edc" src="https://github.com/WordPress/wordpress-playground/assets/205419/2fa204c9-5652-40e1-8903-04feed74d686"> That specific ToC is generated using a custom React component that doesn't seems to handle merging new entries with any pre-existing structure. We could fix it, but since we might soon move to a [Playground-based documentation workflow](https://github.com/adamziel/playground-docs-workflow), investing time in Docusaurus setup doesn't make much sense. I went for the easy way out and moved the information to a new page. ## Testing Instructions Run `nx dev docs-site` locally and confirm the toc on the Steps page is in tact.
WordPress · Apr 19, 2024 · 81d6b24 · 81d6b24
1 parent 33196bf
commit 81d6b24
Show file tree

Hide file tree

Showing 2 changed files with 129 additions and 124 deletions.
diff --git a/packages/docs/site/docs/09-blueprints-api/05-steps-shorthands.md b/packages/docs/site/docs/09-blueprints-api/05-steps-shorthands.md
@@ -0,0 +1,129 @@
+---
+sidebar_position: 4
+---
+
+# Shorthands
+
+You can specify some `steps` using a `shorthand` syntax. The following `steps` are currently supported:
+
+### `login`
+
+Use
+
+```json
+	"login": true,
+```
+
+Or
+
+```json
+{
+	"step": "login",
+	"username": "admin",
+	"password": "password"
+}
+```
+
+### `plugins`
+
+(replaces the `installPlugin` step)
+
+Use
+
+```json
+	"plugins": [
+		"hello-dolly",
+		"https://raw.githubusercontent.com/adamziel/blueprints/trunk/docs/assets/hello-from-the-dashboard.zip"
+	]
+```
+
+Or
+
+```json
+[
+	{
+		"step": "installPlugin",
+		"pluginZipFile": {
+			"resource": "wordpress.org/plugins",
+			"slug": "hello-dolly"
+		}
+	},
+	{
+		"step": "installPlugin",
+		"pluginZipFile": {
+			"resource": "url",
+			"url": "https://raw.githubusercontent.com/adamziel/blueprints/trunk/docs/assets/hello-from-the-dashboard.zip"
+		}
+	}
+]
+```
+
+### `siteOptions`
+
+Use
+
+```json
+	"siteOptions": {
+		"blogname": "My first Blueprint"
+	}
+```
+
+Or
+
+```json
+	"step": "setSiteOptions",
+	"options": {
+		"blogname": "My first Blueprint"
+	}
+```
+
+### `defineWpConfigConsts`
+
+(`constants` only)
+
+Use
+
+```json
+{
+	"step": "defineWpConfigConsts",
+	"consts": {
+		"WP_DISABLE_FATAL_ERROR_HANDLER": true,
+		"WP_DEBUG": true,
+		"WP_DEBUG_DISPLAY": true
+	}
+}
+```
+
+Or
+
+```json
+	{
+		"step": "defineWpConfigConsts",
+		"consts": {
+			"WP_DISABLE_FATAL_ERROR_HANDLER": true
+		}
+	},
+	{
+		"step": "defineWpConfigConsts",
+		"consts": {
+			"WP_DEBUG": true
+		}
+	},
+	{
+		"step": "defineWpConfigConsts",
+		"consts": {
+			"WP_DEBUG_DISPLAY": true
+		}
+	}
+```
+
+---
+
+The `shorthand` syntax and the `step` syntax correspond to each other. Every `step` specified with the `shorthand` syntax is added to the top of the `steps` array in arbitrary order.
+
+:::info **Which should you choose?**
+
+-   Use `shorthands` when **brevity** is your main concern.
+-   Use explicit `steps` when you need more control over the **execution order**.
+
+:::
diff --git a/packages/docs/site/docs/09-blueprints-api/05-steps.md b/packages/docs/site/docs/09-blueprints-api/05-steps.md
@@ -20,130 +20,6 @@ import BlueprintExample from '@site/src/components/Blueprints/BlueprintExample.m
 
 Each step is an object that contains a `step` property that specifies the type of step to run. The rest of the properties depend on the type of step. Learn and try each step type below.
 
-## Shorthands
-
-You can specify some `steps` using a `shorthand` syntax. The following `steps` are currently supported:
-
-### `login`
-
-Use
-
-```json
-	"login": true,
-```
-
-Or
-
-```json
-{
-	"step": "login",
-	"username": "admin",
-	"password": "password"
-}
-```
-
-### `plugins`
-
-(replaces the `installPlugin` step)
-
-Use
-
-```json
-	"plugins": [
-		"hello-dolly",
-		"https://raw.githubusercontent.com/adamziel/blueprints/trunk/docs/assets/hello-from-the-dashboard.zip"
-	]
-```
-
-Or
-
-```json
-	{
-		"step": "installPlugin",
-		"pluginZipFile": {
-			"resource": "wordpress.org/plugins",
-			"slug": "hello-dolly"
-		}
-	},
-	{
-		"step": "installPlugin",
- 		"pluginZipFile": {
-			"resource": "url",
-			"url": "https://raw.githubusercontent.com/adamziel/blueprints/trunk/docs/assets/hello-from-the-dashboard.zip"
-		}
-	}
-```
-
-### `siteOptions`
-
-Use
-
-```json
-	"siteOptions": {
-		"blogname": "My first Blueprint"
-	}
-```
-
-Or
-
-```json
-	"step": "setSiteOptions",
-	"options": {
-		"blogname": "My first Blueprint"
-	}
-```
-
-### `defineWpConfigConsts`
-
-(`constants` only)
-
-Use
-
-```json
-{
-	"step": "defineWpConfigConsts",
-	"consts": {
-		"WP_DISABLE_FATAL_ERROR_HANDLER": true,
-		"WP_DEBUG": true,
-		"WP_DEBUG_DISPLAY": true
-	}
-}
-```
-
-Or
-
-```json
-	{
-		"step": "defineWpConfigConsts",
-		"consts": {
-			"WP_DISABLE_FATAL_ERROR_HANDLER": true
-		}
-	},
-	{
-		"step": "defineWpConfigConsts",
-		"consts": {
-			"WP_DEBUG": true
-		}
-	},
-	{
-		"step": "defineWpConfigConsts",
-		"consts": {
-			"WP_DEBUG_DISPLAY": true
-		}
-	}
-```
-
----
-
-The `shorthand` syntax and the `step` syntax correspond to each other. Every `step` specified with the `shorthand` syntax is added to the top of the `steps` array in arbitrary order.
-
-:::info **Which should you choose?**
-
--   Use `shorthands` when **brevity** is your main concern.
--   Use explicit `steps` when you need more control over the **execution order**.
-
-:::
-
 ---
 
 import BlueprintStep from '@site/src/components/BlueprintsAPI/BlueprintStep';