docs: document external option of navigateTo (#7188)

docs/content/2.guide/3.directory-structure/8.middleware.md

@@ -35,7 +35,7 @@ export default defineNuxtRouteMiddleware((to, from) => {
 
 Nuxt provides two globally available helpers that can be returned directly from the middleware:
 
-1. `navigateTo (route: string | Route, options: { redirectCode: number, replace: boolean )` - Redirects to the given route, within plugins or middleware. It can also be called directly to perform page navigation.
+1. `navigateTo (to: RouteLocationRaw | undefined | null, options: { replace: boolean, redirectCode: number, external: boolean )` - Redirects to the given route, within plugins or middleware. It can also be called directly to perform page navigation.
 2. `abortNavigation (err?: string | Error)` - Aborts the navigation, with an optional error message.
 
 Unlike navigation guards in [the vue-router docs](https://router.vuejs.org/guide/advanced/navigation-guards.html#global-before-guards), a third `next()` argument is not passed, and redirects or route cancellation is handled by returning a value from the middleware. Possible return values are:

docs/content/3.api/1.composables/use-router.md

@@ -19,8 +19,8 @@ If you have a `pages/` folder, `useRouter` is identical in behavior to the one p
 - **back:** Go back in history if possible, same as `router.go(-1)`.
 - **forward:** Go forward in history if possible, same as `router.go(1)`.
 - **go:** Move forward or backward through the history without the hierarchical restrictions enforced in `router.back()` and `router.forward()`.
-- **push:** Programmatically navigate to a new URL by pushing an entry in the history stack. **It is recommended to use [`navigateTo`](http://v3.nuxtjs.org/api/utils/navigate-to#navigateto) instead.**
+- **push:** Programmatically navigate to a new URL by pushing an entry in the history stack. **It is recommended to use [`navigateTo`](http://v3.nuxtjs.org/api/utils/navigate-to) instead.**
-- **replace:** Programmatically navigate to a new URL by replacing the current entry in the routes history stack. **It is recommended to use [`navigateTo`](http://v3.nuxtjs.org/api/utils/navigate-to#navigateto) instead.**
+- **replace:** Programmatically navigate to a new URL by replacing the current entry in the routes history stack. **It is recommended to use [`navigateTo`](http://v3.nuxtjs.org/api/utils/navigate-to) instead.**
 
 > TIP: `router.addRoute()` adds route details into an array of routes and it is useful while building Nuxt plugins while `router.push()` on the other hand, triggers a new navigation immediately and it is useful in Nuxt Page components, Vue components and composable.
 

docs/content/3.api/3.utils/navigate-to.md

@@ -1,76 +1,115 @@
 # `navigateTo`
 
-`navigateTo` is a router helper function that allows creating programmatic navigation for users to navigate within Nuxt application.
+`navigateTo` is a router helper function that allows programmatically navigating users through your Nuxt application.
 
 `navigateTo` is available on both server side and client side. It can be used within plugins, middleware or can be called directly to perform page navigation.
 
-## Usage
+## Type
 
 ```ts
-navigateTo (route: string | Route, { redirectCode = 302, replace = false })
+navigateTo(to: RouteLocationRaw | undefined | null, options?: NavigateToOptions) => Promise<void | NavigationFailure> | RouteLocationRaw
+
+interface NavigateToOptions {
+  replace?: boolean
+  redirectCode?: number
+  external?: boolean
+}
 ```
 
-`route` can be a plain string or a route object to redirect to.
-
 ::alert{type="warning"}
-Make sure to use always `await` or `return` on result of `navigateTo()` when calling it.
+Make sure to always use `await` or `return` on result of `navigateTo` when calling it.
 ::
 
+## Parameters
+
+### `to`
+
+**Type**: [`RouteLocationRaw`](https://router.vuejs.org/api/#routelocationraw) | `undefined` | `null`
+
+**Default**: `'/'`
+
+`to` can be a plain string or a route object to redirect to. When passed as `undefined` or `null`, it will default to `'/'`.
+
+### `options` (optional)
+
+**Type**: `NavigateToOptions`
+
+An object accepting the following properties:
+
+- `replace` (optional)
+
+  **Type**: `boolean`
+
+  **Default**: `false`
+
+  By default, `navigateTo` pushes the given route into the Vue Router's instance on the client side.
+
+  This behavior can be changed by setting `replace` to `true`, to indicate that given route should be replaced.
+
+- `redirectCode` (optional)
+
+  **Type**: `number`
+
+  **Default**: `302`
+
+  `navigateTo` redirects to the given path and sets the redirect code to [`302 Found`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/302) by default when the redirection takes place on the server side.
+
+  This default behavior can be modified by providing different `redirectCode`. Commonly, [`301 Moved Permanently`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/301) can be used for permanent redirections.
+
+- `external` (optional)
+
+  **Type**: `boolean`
+
+  **Default**: `false`
+
+  Allows navigating to an external URL when set to `true`. Otherwise, `navigateTo` will throw an error, as external navigation is not allowed by default.
+
 ## Examples
 
-### Within a Vue Component
+### Navigating Within a Vue Component
 
 ```vue
 <script setup>
-// string
+// passing 'to' as a string
 return navigateTo('/search')
 
-// route object
+// ... or as a route object
 return navigateTo({ path: '/search' })
 
-// route object with query parameters
+// ... or as a route object with query parameters
 return navigateTo({
-    path: '/search',
+  path: '/search',
-    query: {
+  query: {
-        name: name.value,
+    page: 1,
-        type: type.value
+    sort: 'asc'
-    }
+  }
 })
 </script>
 ```
 
-### Within Route Middleware
+### Navigating Within Route Middleware
 
-```js
+```ts
 export default defineNuxtRouteMiddleware((to, from) => {
-  // set the redirect code to 301 Moved Permanently
+  // setting the redirect code to '301 Moved Permanently'
   return navigateTo('/search', { redirectCode: 301 })
 })
 ```
 
-```js
-<script setup>
-    await navigateTo('/', { replace: true })
-</script>
-```
-
 ::ReadMore{link="/guide/directory-structure/middleware"}
 ::
 
-### Options
+### Navigating to an External URL
 
-#### `redirectCode`
+```vue
+<script setup>
+  // will throw an error;
+  // navigating to an external URL is not allowed by default
+  await navigateTo('https://v3.nuxtjs.org')
 
-- Type: Number
+  // will redirect successfully with the 'external' parameter set to 'true'
-
+  await navigateTo('https://v3.nuxtjs.org', {
-`navigateTo` redirects to the given path and sets the redirect code to [`302` Found](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/302) by default when the redirect takes place on the server side.
+    external: true
-
+  })
-This default behavior can be modified by providing different `redirectCode` as an optional parameter. Commonly [`301` Moved Permanently](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/301) can be used for permant redirections.
+</script>
-
+```
-#### `replace`
-
-- Type: Boolean
-
-By default, `navigateTo` pushes the given route into Vue router instance on client-side.
-
-This behavior can be changed by setting `replace` to `true`, to indicate that given route should be replaced.