docs(routing): improvements (#3664)

docs/content/3.docs/1.usage/9.nuxt-link.md

@@ -1,10 +1,8 @@
-# Routing
-
-## `<NuxtLink>`
+# NuxtLink
 
 Nuxt provides `<NuxtLink>` component to handle any kind of links within your application.
 
-`<NuxtLink>` component is a drop-in replacement for both Vue Router's `<RouterLink />` component and HTML's `<a>` tag. It intelligently determines whether the link is _internal_ or _external_ and renders it accordingly with available optimizations (prefetching, default attributes, etc.)
+`<NuxtLink>` is a drop-in replacement for both Vue Router's `<RouterLink>` component and HTML's `<a>` tag. It intelligently determines whether the link is _internal_ or _external_ and renders it accordingly with available optimizations (prefetching, default attributes, etc.)
 
 ## Examples
 

docs/content/3.docs/2.directory-structure/10.pages.md

@@ -6,22 +6,65 @@ head.title: Pages directory
 
 # Pages directory
 
+Nuxt provides a file-based routing to create routes within your web application using [Vue Router](https://router.vuejs.org) under the hood.
+
 ::alert{type="info"}
-The `pages/` directory is optional, meaning that if you only use [app.vue](/docs/directory-structure/app), `vue-router` won't be included, reducing your application's bundle size.
+This directory is **optional**, meaning that [`vue-router`](https://router.vuejs.org) won't be included if you only use [app.vue](/docs/directory-structure/app), reducing your application's bundle size.
 ::
 
-Nuxt will automatically integrate [Vue Router](https://router.vuejs.org/) and map `pages/` directory into the routes of your application.
+## Usage
+
+Pages are Vue components and can have the `.vue`, `.js`, `.jsx`, `.ts` or `.tsx` extension.
+
+::code-group
+
+```vue [pages/index.vue]
+<template>
+  <h1>Index page</h1>
+</template>
+```
+
+```ts [pages/index.ts]
+// https://vuejs.org/guide/extras/render-function.html
+export default defineComponent({
+  render () {
+    return h('h1', 'Index page')
+  }
+})
+```
+
+```ts [pages/index.tsx]
+// https://vuejs.org/guide/extras/render-function.html#jsx-tsx
+export default defineComponent({
+  render () {
+    return <h1>Index page</h1>
+  }
+})
+```
+
+::
+
+The `pages/index.vue` file will be mapped to the `/` route of your application.
+
+If you are using [app.vue](/docs/directory-structure/app), make sure to use the `<NuxtPage/>` component to display the current page:
+
+```vue [app.vue]
+<template>
+  <div>
+    <!-- Markup shared across all pages, ex: NavBar -->
+    <NuxtPage />
+  </div>
+</template>
+```
 
 ::alert{type=warning}
-Unlike components, your pages must have a single root element to allow Nuxt to apply route transitions between pages.
+Note that pages **must have a single root element** to allow route transitions between pages.
 ::
 
 ## Dynamic Routes
 
 If you place anything within square brackets, it will be turned into a [dynamic route](https://router.vuejs.org/guide/essentials/dynamic-matching.html) parameter. You can mix and match multiple parameters and even non-dynamic text within a file name or directory.
 
-If you need a catch-all route, you create it by using a file named like `[...slug].vue`. This will match _all_ routes under that path, and thus it doesn't support any non-dynamic text.
-
 ### Example
 
 ```bash
@@ -33,17 +76,16 @@ If you need a catch-all route, you create it by using a file named like `[...slu
 
 Given the example above, you can access group/id within your component via the `$route` object:
 
-```vue
+```vue [pages/users-[group]/[id].vue]
 <template>
-  {{ $route.params.group }}
-  {{ $route.params.id }}
+  <p>{{ $route.params.group }} - {{ $route.params.id }}</p>
 </template>
 ```
 
 Navigating to `/users-admins/123` would render:
 
-```text
-admins 123
+```html
+<p>admins - 123</p>
 ```
 
 If you want to access the route using Composition API, there is a global `useRoute` function that will allow you to access the route just like `this.$route` in the Options API.
@@ -58,36 +100,22 @@ if (route.params.group === 'admins' && !route.params.id) {
 </script>
 ```
 
-## Navigation
+## Catch all route
 
-To navigate between pages of your app, you should use the  `<NuxtLink>` component. This component is included with Nuxt and therefore you don't have to import it as you do with other components. It is similar to the HTML `<a>` tag except that instead of using a `href="/about"` you use `to="/about"`. If you've used `vue-router` before, you can think of `<NuxtLink>` as a replacement for `<RouterLink>`.
+If you need a catch-all route, you create it by using a file named like `[...slug].vue`. This will match _all_ routes under that path.
 
-A simple link to the `index.vue` page in your `pages` folder:
-
-```html
+```vue [pages/[...slug].vue]
 <template>
-  <NuxtLink to="/">Home page</NuxtLink>
+  <p>{{ $route.params.slug }}</p>
 </template>
 ```
 
-The `<NuxtLink>` component should be used for all internal links. That means for all links to the pages within your site you should use `<NuxtLink>`. The `<a>` tag should be used for all external links. That means if you have links to other websites you should use the `<a>` tag for those.
+Navigating to `/hello/world` would render:
 
 ```html
-<template>
-  <div>
-    <h1>Home page</h1>
-    <NuxtLink to="/about">
-      About (internal link that belongs to the Nuxt App)
-    </NuxtLink>
-    <a href="https://nuxtjs.org">External Link to another page</a>
-  </div>
-</template>
+<p>["hello", "world"]</p>
 ```
 
-::alert{type="info"}
-If you want to know more about `<RouterLink>`, read the [Vue Router documentation](https://router.vuejs.org/api/#router-link) for more information.
-::
-
 ## Nested Routes
 
 It is possible to display [nested routes](https://next.router.vuejs.org/guide/essentials/nested-routes.html) with `<NuxtPage>`.
@@ -171,6 +199,7 @@ This data can then be accessed throughout the rest of your app from the `route.m
 ```vue
 <script setup>
 const route = useRoute()
+
 console.log(route.meta.title) // My home page
 </script>
 ```
@@ -186,7 +215,7 @@ import { someData } from '~/utils/example'
 const title = ref('')
 
 definePageMeta({
-  title,
+  title,  // This will create an error
   someData
 })
 </script>
@@ -215,3 +244,21 @@ You can define middleware to apply before loading this page. It will be merged w
 #### `layoutTransition` and `pageTransition`
 
 You can define transition properties for the `<transition>` components that wraps your pages and layouts, or pass `false` to disable the `<transition>` wrapper for that route. [More about transitions](https://vuejs.org/guide/built-ins/transition.html#transition).
+
+## Navigation
+
+To navigate between pages of your app, you should use the [`<NuxtLink>`](/docs/usage/nuxt-link) component.
+
+This component is included with Nuxt and therefore you don't have to import it as you do with other components.
+
+A simple link to the `index.vue` page in your `pages` folder:
+
+```html
+<template>
+  <NuxtLink to="/">Home page</NuxtLink>
+</template>
+```
+
+::alert{type="info"}
+Learn more about [`<NuxtLink>`](/docs/usage/nuxt-link) usage.
+::

docs/yarn.lock

@@ -11150,10 +11150,10 @@ untyped@^0.2.5, untyped@^0.2.8, untyped@^0.2.9:
   resolved "https://registry.yarnpkg.com/untyped/-/untyped-0.2.9.tgz#3e3df96a303dec3e2eda55fcbdc02e2ab468683d"
   integrity sha512-8d8V+q/y5CGzV+IYnoOCMjrK+NSNp1HKO8iPQ+bV4rBP8knPIme3+j/bpej8IuMnEMxOJZNptXNOXCx7w+VJxQ==
 
-untyped@^0.3.0:
-  version "0.3.0"
-  resolved "https://registry.yarnpkg.com/untyped/-/untyped-0.3.0.tgz#854df4dec055cc6a0a2217aa2d20152277b6ada9"
-  integrity sha512-n4M5/T1wWlHFmohk0EhS+yM7W/h5dOtQldOV3MVEbZY1fTy5A47UL8+d8GLW1iwmaAwNrM5ERy3qe1k0T/Yc7A==
+untyped@^0.4.2:
+  version "0.4.2"
+  resolved "https://registry.yarnpkg.com/untyped/-/untyped-0.4.2.tgz#302e53b1733ff383749342b06f38277af97516ad"
+  integrity sha512-akHdcDop+tvtwPQxrbDfGf6zfQUgMjJXA8hXYYxcnmH6NnuMQatiY9wYDZ+jkUCcWuctb70f/QBYmbMsJpl48g==
 
 upath@^1.1.1:
   version "1.2.0"