From 9665ecee847ebcce4113b9b1346f4d70ff148258 Mon Sep 17 00:00:00 2001
From: Enrico Alvarenga <enricomalvarenga@gmail.com>
Date: Tue, 29 Aug 2023 10:45:58 -0700
Subject: [PATCH] docs(writing-templates): add built in filters section

Signed-off-by: Enrico Alvarenga <enricomalvarenga@gmail.com>
---
 .changeset/tame-jokes-do.md                   | 11 +--
 .../software-templates/writing-templates.md   | 95 +++++++++++++++++++
 2 files changed, 96 insertions(+), 10 deletions(-)

diff --git a/.changeset/tame-jokes-do.md b/.changeset/tame-jokes-do.md
index 35a508e692..8e9b5a6056 100644
--- a/.changeset/tame-jokes-do.md
+++ b/.changeset/tame-jokes-do.md
@@ -3,13 +3,4 @@
 ---
 
 Improved the `parseEntityRef` Scaffolder filter by introducing the ability for users to provide default kind and/or namespace values. The filter now takes
-2 arguments, similarly to the original [parseEntityRef](<(https://github.com/backstage/backstage/blob/v1.17.2/packages/catalog-model/src/entity/ref.ts#L77)>):
-
-1. Entity reference
-2. [Context optional object](https://github.com/backstage/backstage/blob/v1.17.2/packages/catalog-model/src/entity/ref.ts#L77)
-
-Check out the following examples:
-
-- `${{ parameters.entityRef | parseEntityRef | pick('name') }}`
-- `${{ parameters.entityRef | parseEntityRef({ defaultKind:"group", defaultNamespace:"default" }) | pick('name') }}`
-- `${{ parameters.entityRef | parseEntityRef({ defaultKind:"group" }) | pick('name') }}`
+2 arguments, similarly to the original [parseEntityRef](https://github.com/backstage/backstage/blob/v1.17.2/packages/catalog-model/src/entity/ref.ts#L77).
diff --git a/docs/features/software-templates/writing-templates.md b/docs/features/software-templates/writing-templates.md
index 67bcb6c179..3594c395eb 100644
--- a/docs/features/software-templates/writing-templates.md
+++ b/docs/features/software-templates/writing-templates.md
@@ -601,3 +601,98 @@ output things. You can grab that output using `steps.$stepId.output.$property`.
 You can read more about all the `inputs` and `outputs` defined in the actions in
 code part of the `JSONSchema`, or you can read more about our
 [built in actions](./builtin-actions.md).
+
+## Built in Filters
+
+Template filters are functions that help you transform data, extract specific information,
+and perform various operations in Scaffolder Templates.
+
+This section introduces the built-in filters provided by Backstage and offers examples of
+how to use them in the Scaffolder templates. It's important to mention that Backstage also leverages the
+native filters from the Nunjucks library. For a complete list of these native filters and their usage,
+refer to the [Nunjucks documentation](https://mozilla.github.io/nunjucks/templating.html#builtin-filters).
+
+### parseRepoUrl
+
+The `parseRepoUrl` filter parse a repository URL into
+its components, such as `owner`, repository `name`, and more.
+
+**Usage Example:**
+
+```yaml
+- id: log
+  name: Parse Repo URL
+  action: debug:log
+  input:
+    extra: ${{ parameters.repoUrl | parseRepoUrl }}
+```
+
+- **Input**: `https://github.com/backstage/backstage`
+- **Output**: [RepoSpec](https://github.com/backstage/backstage/blob/v1.17.2/plugins/scaffolder-backend/src/scaffolder/actions/builtin/publish/util.ts#L39)
+
+### parseEntityRef
+
+The `parseEntityRef` filter allows you to extract different parts of
+an entity reference, such as the `kind`, `namespace`, and `name`.
+
+**Usage example**
+
+1. Without context
+
+```yaml
+- id: log
+  name: Parse Entity Reference
+  action: debug:log
+  input:
+    extra: ${{ parameters.owner | parseEntityRef }}
+```
+
+- **Input**: `group:techdocs`
+- **Output**: [CompoundEntityRef](https://github.com/backstage/backstage/blob/v1.17.2/packages/catalog-model/src/types.ts#L23)
+
+2. With context
+
+```yaml
+- id: log
+  name: Parse Entity Reference
+  action: debug:log
+  input:
+    extra: ${{ parameters.owner | parseEntityRef({ defaultKind:"group", defaultNamespace:"another-namespace" }) }}
+```
+
+- **Input**: `techdocs`
+- **Output**: [CompoundEntityRef](https://github.com/backstage/backstage/blob/v1.17.2/packages/catalog-model/src/types.ts#L23)
+
+### pick
+
+This `pick` filter allows you to select specific properties from an object.
+
+**Usage Example**
+
+```yaml
+- id: log
+  name: Pick
+  action: debug:log
+  input:
+    extra: ${{ parameters.owner | parseEntityRef | pick('name') }}
+```
+
+- **Input**: `group:techdocs`
+- **Output**: `techndocs`
+
+### projectSlug
+
+The `projectSlug` filter generates a project slug from a repository URL
+
+**Usage Example**
+
+```yaml
+- id: log
+  name: Project Slug
+  action: debug:log
+  input:
+    extra: ${{ parameters.repoUrl | projectSlug }}
+```
+
+- **Input**: `https://github.com/backstage/backstage`
+- **Output**: `backstage/backstage`