diff --git a/docs/features/software-templates/writing-custom-actions.md b/docs/features/software-templates/writing-custom-actions.md
index 07c4891a6c..ff43339ff0 100644
--- a/docs/features/software-templates/writing-custom-actions.md
+++ b/docs/features/software-templates/writing-custom-actions.md
@@ -8,6 +8,40 @@ If you're wanting to extend the functionality of the Scaffolder, you can do so
 by writing custom actions which can be used along side our
 [built-in actions](./builtin-actions.md).
 
+---
+**NOTE**
+
+When adding custom actions, the actions array will **replace the built-in actions too**, so if you
+want to have those as well as your new one, you'll need to do the following:
+
+```ts
+import { createBuiltinActions } from '@backstage/plugin-scaffolder-backend';
+import { ScmIntegrations } from '@backstage/integration';
+
+const integrations = ScmIntegrations.fromConfig(config);
+
+const builtInActions = createBuiltinActions({
+  containerRunner,
+  integrations,
+  config,
+  catalogClient,
+  reader,
+});
+
+const actions = [...builtInActions, createNewFileAction()];
+
+return await createRouter({
+  containerRunner,
+  logger,
+  config,
+  database,
+  catalogClient,
+  reader,
+  actions,
+});
+```
+---
+
 ### Writing your Custom Action
 
 Your custom action can live where you choose, but simplest is to include it
@@ -126,36 +160,6 @@ return await createRouter({
 });
 ```
 
-**NOTE** - the actions array will replace the built-in actions too, so if you
-want to have those as well as your new one, you'll need to do the following:
-
-```ts
-import { createBuiltinActions } from '@backstage/plugin-scaffolder-backend';
-import { ScmIntegrations } from '@backstage/integration';
-
-const integrations = ScmIntegrations.fromConfig(config);
-
-const builtInActions = createBuiltinActions({
-  containerRunner,
-  integrations,
-  config,
-  catalogClient,
-  reader,
-});
-
-const actions = [...builtInActions, createNewFileAction()];
-
-return await createRouter({
-  containerRunner,
-  logger,
-  config,
-  database,
-  catalogClient,
-  reader,
-  actions,
-});
-```
-
 ### List of custom action packages
 
 Here is a list of Open Source custom actions that you can add to your Backstage