Improve scaffolder docs

content/docs/docs-nav.yaml

@@ -121,28 +121,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,25 @@
 ---
-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  
+
+
+### 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 +34,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/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

content/docs/scaffolder/troubleshooting/index.md

@@ -9,11 +9,11 @@ Scaffolder templates are a powerful tool to create software, configurations and
 
 ## Testing
 
-Testing of templates is not well supported in Backstage currently, mostly due to the fact that many scaffolder actions perform side-effects.
+Testing of templates is not well supported in Backstage currently, mostly due to the fact that many Scaffolder actions perform side-effects.
 
 A limited set of functionality exists to preview and edit parameters in a sandbox, and dry-run templates (skipping steps that perform mutations).
 
-You can find these features at `/import/entity-preview`.
+You can find these features at `/create/tools`.
 
 It is also possible to test templates by changing the name and namespace of the template to indicate that it is a preview or test version, then adding it to the catalog via `/import/entity` using the version on a published feature branch.
 This preview template will show up in the list of templates however so it is important to remove the entity after testing to avoid duplication, and also to make sure the title/description indicates that it is a temporary test.
@@ -23,13 +23,13 @@ This preview template will show up in the list of templates however so it is imp
 
 Writing templates can be a little cumbersome at times. We have compiled a list of errors that we have seen in the past, that might help you determine the cause of your issue.
 
-Template YAML input forms can also be tested at `/templates/edit` using a live template preview viewer which speeds up the testing cycle.
+Template YAML input forms can also be tested at `/create/tools` using a live template preview viewer which speeds up the testing cycle.
 
 ![preview-template](./template-preview-tool.webp)
 
 ### Resource not accessible by integration
 
-This error is referring to actions that interact GitHub. It means that the Roadie GitHub app is unable to read, create or update the resource/s that are being touched by the Scaffolder step. 
+This error is referring to actions that interact with GitHub. It means that the Roadie GitHub app is unable to read, create or update the resource/s that are being touched by the Scaffolder step. 
 There can be multiple different reasons for this generic error message that GitHub responds with. Unfortunately the errors returned from GitHub don't provide a lot more information about the specific resources that are being access but below are some cases where it is common to encounter this message.
 
 #### Attempting to create/amend a repository and add collaborators/owners

package.json

@@ -67,6 +67,7 @@
     "react-tabs": "^4.2.1",
     "react-use": "^17.2.4",
     "remark-html": "^13.0.2",
+    "sharp": "^0.33.5",
     "swagger-ui": "^5.9.1",
     "swagger-ui-dist": "^5.9.1",
     "tailwindcss": "^3.0.7"