diff --git a/docs/2.guide/3.going-further/8.custom-routing.md b/docs/2.guide/3.going-further/8.custom-routing.md
index a47d615631..a5c8b708d2 100644
--- a/docs/2.guide/3.going-further/8.custom-routing.md
+++ b/docs/2.guide/3.going-further/8.custom-routing.md
@@ -92,6 +92,27 @@ export default <RouterConfig> {
 }
 ```
 
+It is possible to add more router options files by adding files within the `pages:routerOptions` hook.
+
+::alert
+Adding a router options file in this hook will switch on page-based routing, unless `optional` is set, in which case it will only apply when page-based routing is already enabled.
+::
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  hooks: {
+    'pages:routerOptions' ({ files }) {
+      const resolver = createResolver(import.meta.url)
+      // add a route
+      files.push({
+        path: resolver.resolve('./runtime/app/router-options')
+        optional: true
+      })
+    }
+  }
+})
+```
+
 ### Using `nuxt.config`
 
 **Note:** Only JSON serializable [options](/docs/api/nuxt-config#router) are configurable: