docs(api): add navigateTo docs

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

@@ -41,10 +41,20 @@ Nuxt provides two globally available helpers that can be returned directly from
 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:
 
 * nothing - does not block navigation and will move to the next middleware function, if any, or complete the route navigation
-* `navigateTo('/')` or `navigateTo({ path: '/' })` - redirects to the given path and will set the redirect code to [`302` Found](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/302) if the redirect happens on the server side
-* `navigateTo('/', { redirectCode: 301 })` - redirects to the given path and will set the redirect code to [`301` Moved Permanently](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/301) if the redirect happens on the server side
-* `abortNavigation()` - stops the current navigation
-* `abortNavigation(error)` - rejects the current navigation with an error
+* `return navigateTo('/')` or `return navigateTo({ path: '/' })` - redirects to the given path and will set the redirect code to [`302` Found](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/302) if the redirect happens on the server side
+* `return navigateTo('/', { redirectCode: 301 })` - redirects to the given path and will set the redirect code to [`301` Moved Permanently](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/301) if the redirect happens on the server side
+
+::ReadMore{link="/api/utils/navigate-to"}
+::
+
+* `return abortNavigation()` - stops the current navigation
+* `return abortNavigation(error)` - rejects the current navigation with an error
+
+::ReadMore{link="/api/utils/abort-navigation"}
+::
+
+::ReadMore{link="/guide/features/routing"}
+::
 
 ::alert{type=warning}
 We recommend using the helper functions above for performing redirects or stopping navigation. Other possible return values described in [the vue-router docs](https://router.vuejs.org/guide/advanced/navigation-guards.html#global-before-guards) may work but there may be breaking changes in future.

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

@@ -1,7 +1,76 @@
 # `navigateTo`
 
-::ReadMore{link="/guide/features/routing"}
+`navigateTo` is a router helper function that allows creating programmatic navigation for users to navigate within 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
+
+```ts
+navigateTo (route: string | Route, { redirectCode = 302, replace = false })
+```
+
+`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.
 ::
 
-::NeedContribution
+## Examples
+
+### Within a Vue component
+
+```vue
+<script setup>
+// string
+return navigateTo('/search')
+
+// route object
+return navigateTo({ path: '/search' })
+
+// route object with query parameters
+return navigateTo({
+    path: '/search',
+    query: {
+        name: name.value,
+        type: type.value
+    }
+})
+</script>
+```
+
+### Within route middleware
+
+```js
+export default defineNuxtRouteMiddleware((to, from) => {
+  // set 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
+
+#### `redirectCode`
+
+- Type: Number
+
+`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.
+
+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.
+
+#### `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.