docs: improve router docs on nuxt-injected options (#24126)

docs/2.guide/3.going-further/8.custom-routing.md

@@ -16,8 +16,8 @@ If it returns `null` or `undefined`, Nuxt will fall back to the default routes (
 ```ts [app/router.options.ts]
 import type { RouterConfig } from '@nuxt/schema'
 
-// https://router.vuejs.org/api/interfaces/routeroptions.html
 export default <RouterConfig> {
+  // https://router.vuejs.org/api/interfaces/routeroptions.html#routes
   routes: (_routes) => [
     {
       name: 'home',
@@ -79,25 +79,22 @@ The [Nuxt kit](/docs/guide/going-further/kit) provides a few ways [to add routes
 
 ## Router Options
 
-It is possible to customize [vue-router options](https://router.vuejs.org/api/interfaces/routeroptions.html).
+On top of customizing options for [`vue-router`](https://router.vuejs.org/api/interfaces/routeroptions.html), Nuxt offers [additional options](/docs/api/nuxt-config#router) to customize the router.
 
 ### Using `app/router.options`
 
-It is possible to customize [vue-router options](https://router.vuejs.org/api/interfaces/routeroptions.html).
+This is the recommended way to specify [router options](/docs/api/nuxt-config#router).
-
-This is the recommended way to specify router options.
 
 ```js [app/router.options.ts]
 import type { RouterConfig } from '@nuxt/schema'
 
-// https://router.vuejs.org/api/interfaces/routeroptions.html
 export default <RouterConfig> {
 }
 ```
 
 ### Using `nuxt.config`
 
-**Note:** Only JSON serializable options are configurable:
+**Note:** Only JSON serializable [options](/docs/api/nuxt-config#router) are configurable:
 
 - `linkActiveClass`
 - `linkExactActiveClass`
@@ -105,11 +102,11 @@ export default <RouterConfig> {
 - `sensitive`
 - `strict`
 - `hashMode`
+- `scrollBehaviorType`
 
 ```js [nuxt.config]
 export default defineNuxtConfig({
   router: {
-    // https://router.vuejs.org/api/interfaces/routeroptions.html
     options: {}
   }
 })
@@ -117,7 +114,7 @@ export default defineNuxtConfig({
 
 ### Hash Mode (SPA)
 
-You can enable hash history in SPA mode. In this mode, router uses a hash character (#) before the actual URL that is internally passed. When enabled, the **URL is never sent to the server** and **SSR is not supported**.
+You can enable hash history in SPA mode using the `hashMode` [config](/docs/api/nuxt-config#router). In this mode, router uses a hash character (#) before the actual URL that is internally passed. When enabled, the **URL is never sent to the server** and **SSR is not supported**.
 
 ```ts [nuxt.config.ts]
 export default defineNuxtConfig({
@@ -130,6 +127,20 @@ export default defineNuxtConfig({
 })
 ```
 
+### Scroll Behavior for hash links
+
+You can optionally customize the scroll behavior for hash links. When you set the [config](/docs/api/nuxt-config#router) to be `smooth` and you load a page with a hash link (e.g. `https://example.com/blog/my-article#comments`), you will see that the browser smoothly scrolls to this anchor.
+  
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  router: {
+    options: {
+      scrollBehaviorType: 'smooth'
+    }
+  }
+})
+```
+
 #### Custom History (advanced)
 
 You can optionally override history mode using a function that accepts the base URL and returns the history mode. If it returns `null` or `undefined`, Nuxt will fallback to the default history.
@@ -138,8 +149,8 @@ You can optionally override history mode using a function that accepts the base
 import type { RouterConfig } from '@nuxt/schema'
 import { createMemoryHistory } from 'vue-router'
 
-// https://router.vuejs.org/api/interfaces/routeroptions.html
 export default <RouterConfig> {
+  // https://router.vuejs.org/api/interfaces/routeroptions.html
   history: base => process.client ? createMemoryHistory(base) : null /* default */
 }
 ```

packages/schema/src/config/router.ts

@@ -3,14 +3,29 @@ import { defineUntypedSchema } from 'untyped'
 export default defineUntypedSchema({
   router: {
     /**
-     * Additional options passed to `vue-router`.
+     * Additional router options passed to `vue-router`. On top of the options for `vue-router`,
-     *
+     * Nuxt offers additional options to customize the router (see below).
-     * Note: Only JSON serializable options should be passed by nuxt config.
+     * @note Only JSON serializable options should be passed by Nuxt config.
-     *
      * For more control, you can use `app/router.options.ts` file.
      * @see [documentation](https://router.vuejs.org/api/interfaces/routeroptions.html).
      * @type {typeof import('../src/types/router').RouterConfigSerializable}
      */
-    options: {}
+    options: {
+      /**
+       * You can enable hash history in SPA mode. In this mode, router uses a hash character (#) before
+       * the actual URL that is internally passed. When enabled, the
+       * **URL is never sent to the server** and **SSR is not supported**.
+       * @type {typeof import('../src/types/router').RouterConfigSerializable['hashMode']}
+       * @default false
+       */
+      hashMode: false,
+
+      /**
+       * Customize the scroll behavior for hash links.
+       * @type {typeof import('../src/types/router').RouterConfigSerializable['scrollBehaviorType']}
+       * @default 'auto'
+       */
+      scrollBehaviorType: 'auto'
+    }
   }
 })