Improve scaffolder docs (#1444)

content/docs/docs-nav.yaml

@@ -122,28 +122,28 @@ nav:
           - Publishing Plugins: '/docs/custom-plugins/legacy/artifactory/'
   - Scaffolder:
       - Overview: '/docs/scaffolder/writing-templates/'
-      - Scaffolder Actions:
-          - Actions Directory: '/docs/scaffolder/scaffolder-actions-directory/'
-          - Custom Scaffolder Actions: '/docs/scaffolder/self-hosted-scaffolder-actions/'
-      - Scaffolder Parameters:
-          - Paremeters Guide: '/docs/scaffolder/scaffolder-parameters'
-          - Custom Scaffolder Parameters: '/docs/scaffolder/custom-fields/'
+      - Actions Directory: '/docs/scaffolder/scaffolder-actions-directory/'
+      - Custom Actions: '/docs/scaffolder/self-hosted-scaffolder-actions/'
+      - Parameters: '/docs/scaffolder/scaffolder-parameters/'
+      - Custom Parameters: '/docs/scaffolder/custom-fields/'
+      - Organising Templates: '/docs/scaffolder/certified-templates/'
       - Recipes:
-          - Create RFC: '/docs/scaffolder/create-rfc/'
-          - Debug template: '/docs/scaffolder/debug-template/'
-          - Append file: '/docs/scaffolder/append/'
-          - Re-use parameters: '/docs/scaffolder/global-constants/'
-          - Edit files: '/docs/scaffolder/edit-file/'
-          - Pre-filling templates via URL params: '/docs/scaffolder/predefined-values-via-url-params/'
-          - Manipulate JSON files: '/docs/scaffolder/manipulate-json-files'
-          - Manipulate YAML files: '/docs/scaffolder/manipulate-yaml-files'
-          - Call external API: '/docs/scaffolder/call-external-api'
-          - Transform JSON files with JSONata: '/docs/scaffolder/json-jsonata-transform'
-          - Transform YAML files with JSONata: '/docs/scaffolder/yaml-jsonata-transform'
-          - Using for loops in templates: '/docs/scaffolder/loops-in-templates'
-          - Using for loops to repeat scaffolder steps: '/docs/scaffolder/loops-in-steps'
-          - Assigning variables to the scaffolder context: '/docs/scaffolder/variables-in-scaffolder'
-          - Creating a PR to an Azure DevOps repository: '/docs/scaffolder/azure-actions'
+          - Create RFC: '/docs/scaffolder/recipes/create-rfc/'
+          - Debug template: '/docs/scaffolder/recipes/debug-template/'
+          - Append file: '/docs/scaffolder/recipes/append/'
+          - Re-use parameters: '/docs/scaffolder/recipes/global-constants/'
+          - Re-use steps: '/docs/scaffolder/recipes/placeholders/'
+          - Edit files: '/docs/scaffolder/recipes/edit-file/'
+          - Pre-filling templates via URL params: '/docs/scaffolder/recipes/predefined-values-via-url-params/'
+          - Manipulate JSON files: '/docs/scaffolder/recipes/manipulate-json-files'
+          - Manipulate YAML files: '/docs/scaffolder/recipes/manipulate-yaml-files'
+          - Call external API: '/docs/scaffolder/recipes/call-external-api'
+          - Transform JSON files with JSONata: '/docs/scaffolder/recipes/json-jsonata-transform'
+          - Transform YAML files with JSONata: '/docs/scaffolder/recipes/yaml-jsonata-transform'
+          - Using for loops in templates: '/docs/scaffolder/recipes/loops-in-templates'
+          - Using for loops to repeat scaffolder steps: '/docs/scaffolder/recipes/loops-in-steps'
+          - Assigning variables to the scaffolder context: '/docs/scaffolder/recipes/variables-in-scaffolder'
+          - Creating a PR to an Azure DevOps repository: '/docs/scaffolder/recipes/azure-actions'
   - Tech-Insights:
       - Introduction: '/docs/tech-insights/introduction/'
       - Data Sources:

content/docs/scaffolder/certified-templates/index.md

@@ -1,12 +1,24 @@
 ---
-title: Certified Templates
+title: Organising Templates
 publishedDate: '2023-08-07'
-description: Tutorial to render the certified chip on your scaffolder templates
+description: How to organise and categorize Templates
 ---
 
 ## Overview
 
-Certified templates are templates that got an approval from the owner of the template. They get a certification chip rendered on their template card when you visit the `/create` page.
+When you start getting lots of templates and they start getting used a lot and relied on, organising and categorising them becomes a priority.
+
+### Grouping templates
+
+Roadie Admin users can create groups or categories of templates that will show in the list page. This can be done via the Settings page in the Scaffolder plugin config at `/administration/scaffolder`.
+
+### Certified Templates
+
+![certified-template](./certified.webp)
+
+Certified templates are templates that have an approval from the owner of the template. They get a certification chip rendered on their template card when you visit the `/create` page.
+
+You should only certify templates that are in a mature and stable state. This allows users to safely run a certified template without worrying that it is not working or is incomplete.
 
 The certification chip can be shown on your templates by adding the `roadie.io/certified: "true"` annotation to the template.
 
@@ -21,8 +33,3 @@ spec:
 ...
 ```
 
-![certified-template](./certified.webp)
-
-## Usage
-
-The best practice is to certify your templates that are in a mature state and you are not working on them actively. This way your engineers can safely run all of the certified templates without worrying which template is the one that they should run.

content/docs/scaffolder/custom-fields/index.md

@@ -1,26 +1,25 @@
 ---
-title: Custom Scaffolder Field Extensions
+title: Custom Scaffolder Parameters
 publishedDate: '2024-02-28'
-description: How to develop and register custom Scaffolder Field Extensions 
+description: How to develop and register custom Scaffolder Parameters 
 ---
 
-You can extend and customize the available Scaffolder functionality by using [Roadie Custom Plugins](/docs/custom-plugins/overview/). You can use the same workflow and development experience to build your own Custom Scaffolder Field Extensions as any other plugin, using the Roadie CLI. To see more information on how to develop custom plugins navigate to the Custom Plugins Documentation.
+You can extend and customize the available Scaffolder functionality by using [Roadie Custom Plugins](/docs/custom-plugins/overview/). You can use the same workflow and development experience to build your own Custom Scaffolder Parameters as any other plugin, using the Roadie CLI. To see more information on how to develop custom plugins navigate to the Custom Plugins Documentation.
 
 To see more information on how to develop custom plugins. It is recommended to navigate to the [Custom Plugins Documentation](/docs/custom-plugins/getting-started/). 
 
 
 ### Constructing React components for your Field Extension
 
-To construct the correct type of React components that are compatible to be registered as Scaffolder Field Extensions, the recommended approach is to [follow the tutorial on the Open Source Backstage documentation page.](https://backstage.io/docs/features/software-templates/writing-custom-field-extensions/)
+To construct the correct type of React components that are compatible to be registered as Scaffolder Parameters, the recommended approach is to [follow the tutorial on the Open Source Backstage documentation page.](https://backstage.io/docs/features/software-templates/writing-custom-field-extensions/)
 
-### Registering your Field Extension
+### Registering your Parameter
 
-Scaffolder Field Extensions are automatically registered to be usable within Scaffolder Templates, once they have been registered as a Custom Plugin component to the Roadie application. You can do this by navigating to the `Administration` -> `Custom Plugins` page and registering your Custom Plugin bundle, including a component of type `ScaffolderFieldExtension`.
+Scaffolder Parameter are automatically registered to be usable within Scaffolder Templates, once they have been registered as a Custom Plugin component to the Roadie application. You can do this by navigating to the `Administration` -> `Custom Plugins` page and registering your Custom Plugin bundle, including a component of type `ScaffolderFieldExtension`.
 
 ![Custom plugin registration form](custom_plugin_registration_form.webp)
 
 
-
 ## Additional Resources
 
 * [Roadie CLI](https://www.npmjs.com/package/@roadiehq/roadie-cli)

content/docs/scaffolder/append/index.md → content/docs/scaffolder/recipes/append/index.md

@@ -13,7 +13,7 @@ description: How to append some user defined content to a file and create a new
 - [`publish:github:pull-request`](https://github.com/backstage/backstage/blob/54b9f073d13d878fce652c9ec8b8cdfc5fd85c6a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/publish/githubPullRequest.ts)
 - [`debug:log`](https://github.com/backstage/backstage/blob/54b9f073d13d878fce652c9ec8b8cdfc5fd85c6a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/debug/log.ts)
 
-You can check the available actions if you visit `/templates/actions`.
+You can check the available actions if you visit `/create/actions`.
 
 
 ```yaml

content/docs/scaffolder/azure-actions/index.md → content/docs/scaffolder/recipes/azure-actions/index.md

@@ -11,7 +11,7 @@ description: Clone a repo in Azure DevOps make changes, push and create a PR.
 - [`azure:repo:push`](https://github.com/Parfuemerie-Douglas/scaffolder-backend-module-azure-repositories)
 - [`azure:repo:pr`](https://github.com/Parfuemerie-Douglas/scaffolder-backend-module-azure-repositories)
 
-For more information on these actions and others visit `/templates/actions` in your Roadie application.
+For more information on these actions and others visit `/create/actions` in your Roadie application.
 
 ## Template
 

content/docs/scaffolder/call-external-api/index.md → content/docs/scaffolder/recipes/call-external-api/index.md

@@ -14,7 +14,7 @@ description: An introduction template calling an external API
 - `debug:log`
 - `https:backstage:request`
 
-You can check the available actions if you visit `/templates/actions`.
+You can check the available actions if you visit `/create/actions`.
 
 ## Walkthrough
 

content/docs/scaffolder/create-rfc/index.md → content/docs/scaffolder/recipes/create-rfc/index.md

@@ -13,7 +13,7 @@ description: An introduction template to creating an RFC
 - [`fs:rename`](https://github.com/backstage/backstage/blob/54b9f073d13d878fce652c9ec8b8cdfc5fd85c6a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/filesystem/rename.ts)
 - [`publish:github:pull-request`](https://github.com/backstage/backstage/blob/54b9f073d13d878fce652c9ec8b8cdfc5fd85c6a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/publish/githubPullRequest.ts)
 
-You can check the available actions if you visit `/templates/actions`.
+You can check the available actions if you visit `/create/actions`.
 
 ## Walkthrough
 

content/docs/scaffolder/debug-template/index.md → content/docs/scaffolder/recipes/debug-template/index.md

@@ -16,7 +16,7 @@ description: Template to fetch and render the content of your skeleton template
 - `fs:read`
 - [`debug:log`](https://github.com/backstage/backstage/blob/54b9f073d13d878fce652c9ec8b8cdfc5fd85c6a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/debug/log.ts)
 
-You can check the available actions if you visit `/templates/actions`.
+You can check the available actions if you visit `/create/actions`.
 
 ## Walkthrough
 

content/docs/scaffolder/edit-file/index.md → content/docs/scaffolder/recipes/edit-file/index.md

@@ -20,7 +20,7 @@ Proper editing functionality is not well supported by Backstage at the moment th
 - [`publish:github:pull-request`](https://github.com/backstage/backstage/blob/54b9f073d13d878fce652c9ec8b8cdfc5fd85c6a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/publish/githubPullRequest.ts)
 - [`debug:log`](https://github.com/backstage/backstage/blob/54b9f073d13d878fce652c9ec8b8cdfc5fd85c6a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/debug/log.ts)
 
-You can check the available actions if you visit `/templates/actions`.
+You can check the available actions if you visit `/create/actions`.
 
 ### Example Template
 
@@ -114,7 +114,7 @@ spec:
 - [`publish:github:pull-request`](https://github.com/backstage/backstage/blob/54b9f073d13d878fce652c9ec8b8cdfc5fd85c6a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/publish/githubPullRequest.ts)
 - [`debug:log`](https://github.com/backstage/backstage/blob/54b9f073d13d878fce652c9ec8b8cdfc5fd85c6a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/debug/log.ts)
 
-You can check the available actions if you visit `/templates/actions`.
+You can check the available actions if you visit `/create/actions`.
 
 ### Example Template
 
@@ -198,7 +198,7 @@ spec:
 - [`publish:github:pull-request`](https://github.com/backstage/backstage/blob/54b9f073d13d878fce652c9ec8b8cdfc5fd85c6a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/publish/githubPullRequest.ts)
 - [`debug:log`](https://github.com/backstage/backstage/blob/54b9f073d13d878fce652c9ec8b8cdfc5fd85c6a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/debug/log.ts)
 
-You can check the available actions if you visit `/templates/actions`.
+You can check the available actions if you visit `/create/actions`.
 
 ### Example Template
 

content/docs/scaffolder/global-constants/index.md → content/docs/scaffolder/recipes/global-constants/index.md

@@ -11,8 +11,9 @@ description: If you want to have a centrally defined re-useable parameter value
 - [`placeholders`](https://backstage.io/docs/features/software-catalog/descriptor-format#substitutions-in-the-descriptor-format)
 - [`debug:log`](https://github.com/backstage/backstage/blob/54b9f073d13d878fce652c9ec8b8cdfc5fd85c6a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/debug/log.ts)
 
-You can check the available actions if you visit `/templates/actions`.
+You can check the available actions if you visit `/create/actions`.
 
+### Relative file
 
 ```yaml
 ---
@@ -40,6 +41,41 @@ spec:
 ./constants/products.yaml
 ```yaml
 title: Select Product
+properties:
+  product:
+    title: Product
+    type: string
+    enum: ["Search", "CRM", "Onboarding"]
+```
+
+### External File
+
+```yaml
+---
+apiVersion: scaffolder.backstage.io/v1beta3
+kind: Template
+metadata:
+  name: global-param-example
+  title: Example of sourcing params from a constant
+spec:
+  owner: roadie
+  type: service
+
+  parameters:
+    - $yaml: https://github.com/RoadieHQ/software-templates/tree/main/scaffolder-templates/parameters/products.yaml
+
+  steps:
+    - id: log-message
+      name: List selected product
+      action: debug:log
+      input:
+        message: 'Selected product: ${{ parameters.product }}'
+```
+
+
+https://github.com/RoadieHQ/software-templates/tree/main/scaffolder-templates/parameters/products.yaml
+```yaml
+title: Select Product
 properties:
   product:
     title: Product

content/docs/scaffolder/json-jsonata-transform/index.md → content/docs/scaffolder/recipes/json-jsonata-transform/index.md

@@ -10,7 +10,7 @@ description: An introduction template utilizing the roadiehq:utils:jsonata:json:
 - `roadiehq:utils:fs:write`
 - `roadiehq:utils:jsonata:json:transform`
 
-You can check the available actions if you visit `/templates/actions`.
+You can check the available actions if you visit `/create/actions`.
 
 ## Walkthrough
 

content/docs/scaffolder/loops-in-steps/index.md → content/docs/scaffolder/recipes/loops-in-steps/index.md

@@ -10,7 +10,7 @@ description: An example template that uses the Scaffolder step `each` key word t
 
 - [`debug:log`](https://github.com/backstage/backstage/blob/54b9f073d13d878fce652c9ec8b8cdfc5fd85c6a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/debug/log.ts)
 
-You can check the available actions if you visit `/templates/actions`.
+You can check the available actions if you visit `/create/actions`.
 
 ## Walkthrough
 

content/docs/scaffolder/loops-in-templates/index.md → content/docs/scaffolder/recipes/loops-in-templates/index.md

@@ -12,7 +12,7 @@ description: An example template that uses Nunjucks builtin looping functionalit
 - [`fetch:template`](https://github.com/backstage/backstage/blob/54b9f073d13d878fce652c9ec8b8cdfc5fd85c6a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/fetch/template.ts)
 - [`roadiehq:utils:fs:parse`](https://github.com/RoadieHQ/roadie-backstage-plugins/blob/main/plugins/scaffolder-actions/scaffolder-backend-module-utils/src/actions/fs/parseFile.ts)
 
-You can check the available actions if you visit `/templates/actions`.
+You can check the available actions if you visit `/create/actions`.
 
 ## Walkthrough
 

content/docs/scaffolder/manipulate-json-files/index.md → content/docs/scaffolder/recipes/manipulate-json-files/index.md

@@ -12,7 +12,7 @@ description: An introduction template utilizing the JSON editing actions
 - `roadiehq:utils:fs:parse`
 - `roadiehq:utils:serialize:json`
 
-You can check the available actions if you visit `/templates/actions`.
+You can check the available actions if you visit `/create/actions`.
 
 ## Walkthrough
 

content/docs/scaffolder/manipulate-yaml-files/index.md → content/docs/scaffolder/recipes/manipulate-yaml-files/index.md

@@ -12,7 +12,7 @@ description: An introduction template utilizing the YAML editing actions
 - `roadiehq:utils:fs:parse`
 - `roadiehq:utils:serialize:yaml`
 
-You can check the available actions if you visit `/templates/actions`.
+You can check the available actions if you visit `/create/actions`.
 
 ## Walkthrough
 

content/docs/scaffolder/recipes/placeholders/index.md

@@ -0,0 +1,66 @@
+---
+title: Refer to steps defined in another repo
+publishedDate: '2024-12-03'
+description: If you want to have a centrally defined, re-useable step you can use the following pattern
+---
+
+## Template
+
+## Actions used
+
+- [`placeholders`](https://backstage.io/docs/features/software-catalog/descriptor-format#substitutions-in-the-descriptor-format)
+- [`debug:log`](https://github.com/backstage/backstage/blob/master/plugins/scaffolder-backend/src/scaffolder/actions/builtin/debug/log.ts)
+
+You can check the available actions in Roadie if you visit `/create/actions`.
+
+### Relative path
+
+```yaml
+---
+apiVersion: scaffolder.backstage.io/v1beta3
+kind: Template
+metadata:
+  name: re-useable-step-example
+  title: Example of sourcing a step from a constant
+spec:
+  owner: roadie
+  type: service
+
+  steps:
+    - $yaml: './constants/log.yaml'
+```
+
+
+./constants/log.yaml
+```yaml
+id: log-message
+action: debug:log
+input:
+  message: 'Hello there'
+```
+
+### External file
+
+```yaml
+---
+apiVersion: scaffolder.backstage.io/v1beta3
+kind: Template
+metadata:
+  name: re-useable-step-example
+  title: Example of sourcing a step from a constant
+spec:
+  owner: roadie
+  type: service
+
+  steps:
+    - $yaml: 'https://github.com/RoadieHQ/software-templates/tree/main/scaffolder-templates/steps/log.yaml'
+```
+
+
+https://github.com/RoadieHQ/software-templates/tree/main/scaffolder-templates/steps/log.yaml
+```yaml
+id: log-message
+action: debug:log
+input:
+  message: 'Hello there'
+```

content/docs/scaffolder/variables-in-scaffolder/index.md → content/docs/scaffolder/recipes/variables-in-scaffolder/index.md

@@ -11,7 +11,7 @@ description: An example template displaying how to use JSONata to assign variabl
 - [`debug:log`](https://github.com/backstage/backstage/blob/54b9f073d13d878fce652c9ec8b8cdfc5fd85c6a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/debug/log.ts)
 - [`roadiehq:utils:jsonata`](https://github.com/RoadieHQ/roadie-backstage-plugins/blob/main/plugins/scaffolder-actions/scaffolder-backend-module-utils/src/actions/jsonata/jsonata.ts)
 
-You can check the available actions if you visit `/templates/actions`.
+You can check the available actions if you visit `/create/actions`.
 
 ## Walkthrough
 

content/docs/scaffolder/yaml-jsonata-transform/index.md → content/docs/scaffolder/recipes/yaml-jsonata-transform/index.md

@@ -10,7 +10,7 @@ description: An introduction template utilizing the roadiehq:utils:jsonata:yaml:
 - `roadiehq:utils:fs:write`
 - `roadiehq:utils:jsonata:yaml:transform`
 
-You can check the available actions if you visit `/templates/actions`.
+You can check the available actions if you visit `/create/actions`.
 
 ## Walkthrough
 

content/docs/scaffolder/scaffolder-actions-directory/index.md

@@ -11,7 +11,7 @@ Roadie comes bundled with a select set of actions to use out of the box. If you
 If you want to add an action to this list, please [raise an issue on our repo](https://github.com/RoadieHQ/marketing-site/issues) or contribute a PR with the addition.
 
 **NB:**
-- A subset of available actions in Roadie can also be **found at the following page inside your Roadie app**: `https://<tenant-name>.roadie.so/templates/actions`
+- A subset of available actions in Roadie can also be **found at the following page inside your Roadie app**: `https://<tenant-name>.roadie.so/create/actions`
 - We do not list actions created for hackathons and talks that are not maintained or intended for widespread use.
 
 ## Actions Summary Table