From 7f6b88783b585757038378aca59f51d265b8cd2d Mon Sep 17 00:00:00 2001
From: Patrik Oldsberg <poldsberg@gmail.com>
Date: Sat, 4 Apr 2026 16:15:01 +0200
Subject: [PATCH] docs: address review feedback on route refs, typos, and
 installation steps

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>
Made-with: Cursor
---
 .../software-catalog/catalog-customization.md | 21 +++++++++++++++++--
 .../writing-custom-field-extensions.md        |  2 +-
 docs/features/techdocs/getting-started.md     |  2 +-
 docs/features/techdocs/how-to-guides.md       |  7 +++++--
 4 files changed, 26 insertions(+), 6 deletions(-)

diff --git a/docs/features/software-catalog/catalog-customization.md b/docs/features/software-catalog/catalog-customization.md
index e148c6da08..33789c9b9e 100644
--- a/docs/features/software-catalog/catalog-customization.md
+++ b/docs/features/software-catalog/catalog-customization.md
@@ -91,6 +91,19 @@ export default createFrontendModule({
 });
 ```
 
+Then register the module in your app:
+
+```tsx title="packages/app/src/App.tsx"
+import { createApp } from '@backstage/frontend-defaults';
+import catalogCustomizations from './catalog/catalogCustomizations';
+
+const app = createApp({
+  features: [catalogCustomizations],
+});
+
+export default app.createRoot();
+```
+
 ### Removing default filters
 
 Default filters can be disabled through `app-config.yaml` by setting them to `false`:
@@ -117,13 +130,17 @@ you can override the page extension using a frontend module:
 import {
   PageBlueprint,
   createFrontendModule,
+  createRouteRef,
 } from '@backstage/frontend-plugin-api';
 
 const customCatalogPage = PageBlueprint.make({
   params: {
     path: '/catalog',
-    loader: () =>
-      import('./CustomCatalogPage').then(m => <m.CustomCatalogPage />),
+    routeRef: createRouteRef({ aliasFor: 'catalog.catalogIndex' }),
+    loader: async () => {
+      const { CustomCatalogPage } = await import('./CustomCatalogPage');
+      return <CustomCatalogPage />;
+    },
   },
 });
 
diff --git a/docs/features/software-templates/writing-custom-field-extensions.md b/docs/features/software-templates/writing-custom-field-extensions.md
index 0a09d4baa8..94505aa2fd 100644
--- a/docs/features/software-templates/writing-custom-field-extensions.md
+++ b/docs/features/software-templates/writing-custom-field-extensions.md
@@ -293,7 +293,7 @@ export const MyCustomFieldWithOptionsExtension = FormFieldBlueprint.make({
 
 We recommend using a library like [zod](https://github.com/colinhacks/zod) to define your schema
 and the provided `makeFieldSchemaFromZod` helper utility function to generate both the JSON schema
-and type for your field props to preventing having to duplicate the definitions:
+and type for your field props to prevent having to duplicate the definitions:
 
 ```tsx
 // packages/app/src/scaffolder/MyCustomExtensionWithOptions/MyCustomExtensionWithOptions.tsx
diff --git a/docs/features/techdocs/getting-started.md b/docs/features/techdocs/getting-started.md
index d9706c1de8..db5c5d1c17 100644
--- a/docs/features/techdocs/getting-started.md
+++ b/docs/features/techdocs/getting-started.md
@@ -155,7 +155,7 @@ Please be aware that the version requirement could change, you need to check our
 
 On a Debian-based Docker container, Python packages must be either installed using the OS package manager or within a virtual environment (see the [related PEP](https://peps.python.org/pep-0668/)). Alternative is to use e.g. [pipx](https://pypa.github.io/pipx/) for installing Python packages in an isolated environment.
 
-The above Dockerfile snippet installs the latest `mkdocs-techdoc-core` package. Version numbers can be found in the corresponding [changelog](https://github.com/backstage/mkdocs-techdocs-core#changelog). In case you want to pin the version, use the example below:
+The above Dockerfile snippet installs the latest `mkdocs-techdocs-core` package. Version numbers can be found in the corresponding [changelog](https://github.com/backstage/mkdocs-techdocs-core#changelog). In case you want to pin the version, use the example below:
 
 ```Dockerfile
 RUN pip3 install mkdocs-techdocs-core==1.2.3
diff --git a/docs/features/techdocs/how-to-guides.md b/docs/features/techdocs/how-to-guides.md
index 9131d5c8da..10b8270283 100644
--- a/docs/features/techdocs/how-to-guides.md
+++ b/docs/features/techdocs/how-to-guides.md
@@ -138,8 +138,11 @@ export default techdocsPlugin.withOverrides({
     PageBlueprint.make({
       params: {
         path: '/docs',
-        loader: () =>
-          import('./CustomTechDocsHome').then(m => <m.CustomTechDocsHome />),
+        routeRef: techdocsPlugin.routes.root,
+        loader: async () => {
+          const { CustomTechDocsHome } = await import('./CustomTechDocsHome');
+          return <CustomTechDocsHome />;
+        },
       },
     }),
   ],