feat(docs): extendPages

docs/3.api/4.advanced/2.kit.md

@@ -1112,7 +1112,56 @@ export default defineNuxtModule({
 
 [source code](https://github.com/nuxt/nuxt/blob/main/packages/kit/src/pages.ts)
 
-- `extendPages (callback: pages => void)`
+### `extendPages`
+
+In Nuxt 3, routes are automatically generated based on the structure of the files in the `pages` directory. However, there may be scenarios where you'd want to customize these routes. For instance, you might need to add a route for a dynamic page not generated by Nuxt, remove an existing route, or modify the configuration of a route. For such customizations, Nuxt 3 offers the `extendPages` feature, which allows you to extend and alter the pages configuration.
+
+#### Type
+
+```ts
+function extendPages (callback: (pages: NuxtPage[]) => void) => void
+
+type NuxtPage = {
+  name?: string
+  path: string
+  file?: string
+  meta?: Record<string, any>
+  alias?: string[] | string
+  redirect?: RouteLocationRaw
+  children?: NuxtPage[]
+}
+```
+
+#### Parameters
+
+##### `callback`
+
+**Type**: `(pages: NuxtPage[]) => void`
+
+**Required**: `true`
+
+A function that will be called with the pages configuration. You can alter this array by adding, deleting, or modifying its elements. Note: You should modify the provided pages array directly, as changes made to a copied array will not be reflected in the configuration.
+
+#### Examples
+
+```ts
+// https://github.com/nuxt-modules/prismic/blob/master/src/module.ts
+import { createResolver, defineNuxtModule, extendPages } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  setup(options) {
+    const resolver = createResolver(import.meta.url)
+    extendPages((pages) => {
+			pages.unshift({
+			  name: 'prismic-preview',
+        path: '/preview',
+				file: resolver.resolve('runtime/preview.vue')
+			})
+		})
+  }
+})
+```
+
 - `extendRouteRules (route: string, rule: NitroRouteConfig, options: ExtendRouteRulesOptions)`
 - `addRouteMiddleware (input: NuxtMiddleware | NuxtMiddleware[], options: AddRouteMiddlewareOptions)`