Merge pull request #28795 from backstage/techdocs-collator-filter-extension

Custom catalog filtering within TechDocs collator
2025-03-13 13:24:01 -04:00
parent 04b7445c35 e7a3b2ed2e
commit ba409c3d54
6 changed files with 185 additions and 73 deletions
@@ -134,6 +134,38 @@ search:
        timeout: { minutes: 3 }
 ```

+### Filtering through the catalog collator
+
+The TechDocs collator by default filters through catalog entities where the annotation `metadata.annotations.backstage.io/techdocs-ref` exists. If you wish to further filter out entities, there are two ways to do so through the `techDocsCollatorEntityFilterExtensionPoint`.
+
+```typescript
+export const exampleCustomCatalogFiltering = createBackendModule({
+  pluginId: 'search',
+  moduleId: 'search-techdocs-collator-entity-filter',
+  register(reg) {
+    reg.registerInit({
+      deps: {
+        customCollatorFilter: techDocsCollatorEntityFilterExtensionPoint,
+      },
+      async init({ customCollatorFilter }) {
+        /* filtering by catalog params */
+        customCollatorFilter.setCustomCatalogApiFilters([
+          { kind: ['API', 'Component', ...] },
+          { metadata: ['...more filters'] },
+        ]);
+
+        /* filtering by a custom function */
+        customCollatorFilter.setEntityFilterFunction((entities: Entity[]) =>
+          entities.filter(
+            entity => entity.metadata?.annotations?.abc === 'xyz',
+          ),
+        );
+      },
+    });
+  },
+});
+```
+
 ## Community Collators

 Here are some of the known Search Collators available in from the Backstage Community: