Add a how to guide on the recipe builder

Also removes the existing recipe builder doc that was out of
date and wrong.

SUMMARY.md

@@ -7,10 +7,10 @@
 * [Quick Start: Running your first recipe](user-documentation/running-your-first-recipe.md)
 * [Introduction to Type-Aware Code Search](user-documentation/introduction-to-type-aware-code-search.md)
 * [Achieve and Maintain High Code Quality](user-documentation/code-quality.md)
+* [Creating Custom Recipes With the Recipe Builder](how-to/creating-your-own-recipes-with-builder.md)
 
 ## How-to Guides <a href="#how-to" id="how-to"></a>
 
-* [Creating your own recipes with Builder](how-to/creating-your-own-recipes-with-builder.md)
 * [Integrating private code with Moderne SaaS](how-to/integrating-private-code.md)
 * [Importing external recipes](how-to/importing-external-recipes.md)
 * [Terraform Cloud integration](how-to/terraform-cloud-integration.md)

how-to/creating-your-own-recipes-with-builder.md

@@ -1,52 +0,0 @@
-# Creating your own recipes with Builder
-
-Moderne provides the ability to create custom recipes from our existing recipe catalog through _Recipe_ _Builder._
-
-The Recipe Builder allows you to:
-
-1. Import declarative recipes authored in YAML.
-2. Export declarative recipes as YAML and include them in your project.
-3. Remix existing recipes and configurations to meet your goals.
-
-Let's build a custom recipe!
-
-## Step 1: Import an example recipe
-
-Let's start with a simple recipe to import.
-
-```yaml
-type: specs.openrewrite.org/v1beta/recipe
-name: org.your_user_name.MyCustomRecipe
-displayName: My custom recipe
-description: Find instances of List.
-recipeList:
-  - org.openrewrite.java.search.FindTypes:
-      fullyQualifiedTypeName: java.util.List
-      checkAssignability: true
-```
-
-1. Click _Import YAML_ to open the form
-2. Paste in the contents of the recipe above.
-3. Click _import_
-
-   ![](../.gitbook/assets/builder-meta-data.png)
-
-4. Observe the _Recipe List_ now contains our `FindTypes` recipe and configuration
-
-## Step 2: Change options
-
-Once we have imported a recipe from YAML, we can make further modifications before running the recipe.
-
-1. Click the _Settings_ button \(Gear\) next to `Find Types` to open the recipe editor.
-2. Change `java.util.List` to `java.util.Set`
-3. Click _Update_
-4. Observe in the _Recipe Preview_ on the right side that the recipe configuration updated.
-
-## Step 3: Confirm repository selection
-
-In the _Recipe Meta Data_ form, you can select which repositories to include in the recipe run.
-
-## Step 4: Run recipe
-
-Click _Dry Run_ to execute your custom recipe and view the results.
-

user-documentation/recipe-builder.md

@@ -0,0 +1,79 @@
+# Creating Custom Recipes With the Recipe Builder
+
+Have you found a recipe in Moderne where you only want to run certain parts of it? Or have you found a few recipes that you want to combine into one larger recipe? Or maybe you want to run a bunch of recipes in a specific order? 
+
+All of these problems can be solved by utilizing the Recipe Builder, which provides a way for you to create custom recipes from our existing recipe catalog.
+
+To help you get acquainted with the Recipe Builder, in this guide, you will learn:
+* [How to create a custom recipe](#how-to-create-a-custom-recipe)
+* [How to save and share custom recipes](#how-to-save-and-share-custom-recipes)
+* [How to import and run custom recipes](#how-to-import-and-run-custom-recipes)
+
+## How to create a custom recipe
+
+To create a custom recipe you will need to:
+
+1. Find the recipes you want to utilize in your custom recipe
+2. [Add the recipes to the builder](#adding-recipes-to-the-builder)
+3. [Order the recipes to match your needs](#ordering-the-recipes)
+
+### Adding recipes to the builder
+
+There are two possible ways of adding a recipe to the builder:
+
+1. By pressing the `Add to Builder` button in the recipe catalog or in the recipe itself:
+
+    ![](../.gitbook/assets/recipe-catalog-builder.png)
+    
+2. By pressing the `Add Selected to Builder` button that's available on all composite recipes (recipes that have multiple recipes that run as part of them):
+
+    ![](../.gitbook/assets/add-selected-recipe.png)
+
+If you press the `Add to Builder` button, the default version of the recipe and all sub-recipes (if they exist) will be added to the Recipe Builder as one high-level entry. You won't be able to individually configure or see the sub-recipes:
+
+![](../.gitbook/assets/single-recipe.png)
+
+If you want more configurability for composite recipes, such as the ability to change option values, re-order, or remove the sub-recipes, you'll need to press the `Add Selected to Builder` button. This will add an entry for each of the sub-recipes themselves rather than the high-level recipe:
+
+![](../.gitbook/assets/multi-recipe.png)
+
+If any of these recipes have options that you can configure, a wrench icon will appear on the right-hand side. You can click on it to change those options:
+
+![](../.gitbook/assets/expanded-recipe.png)
+
+### Ordering the recipes
+
+Recipes added to the recipe list are run in the order they're listed. This means that if you had a recipe that changed the name of a package from `foo` to `bar` and another recipe, listed after the first one, that changed `bar` to `baz`, you would end up with both `foo` and `bar` changing to `baz`. 
+
+You can re-order the recipes in the recipe list by dragging them up and down:
+
+![](../.gitbook/assets/recipe-reorder.gif)
+
+## How to save and share custom recipes 
+
+Once you've defined and configured all of the recipes you want as part of your custom recipe, you can save it by filling out the `Recipe Meta Data` and pressing download:
+
+![](../.gitbook/assets/recipe-download.png)
+
+This will create and download a YAML file that contains all of the information needed to re-create this recipe. You can either use that file to [re-create this recipe](#how-to-import-and-run-custom-recipes) when needed or you can send that file to anyone and they'll be able to [import it](#how-to-import-and-run-custom-recipes) and run the recipe themselves. 
+
+## How to import and run custom recipes
+
+If you or someone on your team has previously created a recipe via the Recipe Builder, you can import it by following these instructions: 
+
+* Navigate to the [Recipe Builder page](https://public.moderne.io/recipes/builder).
+
+* Press the `Import YAML` button in the top right corner:
+
+    ![](../.gitbook/assets/import-yaml.png)
+
+* A modal will appear that you can paste a declarative YAML recipe into:
+
+    ![](../.gitbook/assets/declarative-yaml.png)
+
+* When you're done entering the YAML, press the `Import` button in the bottom left corner of the modal. If the YAML is properly formatted, you'll see your recipe populated into the recipe builder with everything set up exactly as specified. 
+
+* You can then run the recipe as normal by pressing `Dry Run`:
+  
+    ![](../.gitbook/assets/imported-recipe-run.png)
+