Merge branch 'nuxt:main' into main

.github/workflows/docs-e2e.yml

@@ -0,0 +1,32 @@
+name: docs-e2e
+
+on:
+  workflow_dispatch:
+    inputs:
+      url:
+        required: false
+        description: The URL to run the test suite against.
+        type: string
+  deployment_status:
+
+jobs:
+  crawl-docs:
+    environment:
+      name: ${{ github.event.deployment.environment || 'Production' }}
+      url: ${{ github.event.inputs.url || github.event.deployment.payload.web_url || github.event.deployment_status.target_url }}
+    if: github.event.deployment_status.state == 'success' || github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: ${{ matrix.node }}
+          cache: "yarn"
+
+      - name: Install dependencies
+        run: yarn --immutable
+
+      - run: node ./scripts/crawl.mjs
+        env:
+          BASE_URL: ${{ github.event.inputs.url || github.event.deployment.payload.web_url || github.event.deployment_status.target_url }}

docs/content/2.guide/1.concepts/1.introduction.md → docs/content/1.getting-started/1.introduction.md

@@ -42,7 +42,7 @@ Nuxt is the backbone of your Vue.js project, giving structure to build your proj
 Extendable with a strong module ecosystem and hooks engine, it makes it easy to connect your REST or GraphQL endpoints, favorite CMS, CSS frameworks and more. PWA and AMP support is only a module away from your Nuxt project.
 
 ::alert{type=info icon=👍}
-Ready to try? Head over to the [Installation section](/getting-started/quick-start).
+Ready to try? Head over to the [Installation section](/getting-started/installation).
 ::
 
 ### Are You *Courageously* Nuxt?

docs/content/1.getting-started/1.quick-start.md → docs/content/1.getting-started/2.installation.md

@@ -1,4 +1,4 @@
-# Quick Start
+# Installation
 
 Starting fresh? Getting started with Nuxt 3 is straightforward!
 
@@ -104,4 +104,3 @@ Well done! A browser window should automatically open for <http://localhost:3000
 Now that you've created your Nuxt 3 project, you are ready to start building your application.
 
 * Learn about the framework [concepts](/guide/concepts)
-* Learn more about the framework [features](/guide/features)

docs/content/2.guide/2.features/3.assets.md → docs/content/1.getting-started/4.assets.md

@@ -70,8 +70,6 @@ In your `nuxt.config`
 ::code-group
 
 ```ts [SCSS]
-import { defineNuxtConfig } from 'nuxt'
-
 export default defineNuxtConfig({
   vite: {
     css: {
@@ -86,8 +84,6 @@ export default defineNuxtConfig({
 ```
 
 ```ts [SASS]
-import { defineNuxtConfig } from 'nuxt'
-
 export default defineNuxtConfig({
   vite: {
     css: {

docs/content/1.getting-started/5.routing.md

@@ -0,0 +1,115 @@
+# Routing
+
+One of Nuxt core feature is the file-system router. Every Vue file created inside the pages/ directory creates a corresponding URL (or route) that displays the content of the file. Nuxt leverages code-splitting on each page by using dynamic imports to ship the minimum of JavaScript for the requested route.
+
+## Pages
+
+Nuxt routing is based on [vue-router](https://router.vuejs.org/) and generates the routes from every component created in the [`pages/`](/guide/directory-structure/pages) directory, based on their filename.
+
+This file system routing uses naming conventions to create dynamic and nested routes:
+
+::code-group
+
+```text [pages/ directory]
+pages/
+--| about.vue
+--| posts/
+----| [id].vue
+```
+
+```js [Generated Router file]
+{
+  "routes": [
+    {
+      "path": "/about",
+      "component": "pages/about.vue"
+    },
+    {
+      "path": "/posts/:id",
+      "component": "pages/posts/[id].vue"
+    }
+  ]
+}
+```
+
+::
+
+## Navigation
+
+The `<NuxtLink>` component links pages between them. It renders a `<a>` tag with the `href` attribute set to the route of the page. Once the application is hydrated, pages transitions are performed in JavaScript by updating the browser URL. This prevents full-page refreshes and allow for animated transitions.
+
+When a `<NuxtLink>` enters the viewport on the client side, Nuxt will automatically prefetch components and payload (generated pages) of the linked pages ahead of time, resulting in faster navigation.
+
+```vue [pages/app.vue]
+<template>
+  <header>
+    <nav>
+      <ul>
+        <li><NuxtLink to="/about">About</NuxtLink></li>
+        <li><NuxtLink to="/posts/1">Post 1</NuxtLink></li>
+        <li><NuxtLink to="/posts/2">Post 2</NuxtLink></li>
+      </ul>
+    </nav>
+  </header>
+</template>
+```
+
+:ReadMore{link="/api/components/nuxt-link"}
+
+## Route Parameters
+
+The `useRoute()` composable can be used in a `<script setup>` block or a `setup()` method of a Vue component to access the current route details.
+
+```vue [pages/post/[id].vue]
+<script setup>
+const route = useRoute()
+
+// When accessing /posts/1, route.params.id will be 1
+console.log(route.params.id)
+</script>
+```
+
+:ReadMore{link="/api/composables/use-route"}
+
+## Route Middleware
+
+Nuxt provides a customizable route middleware framework you can use throughout your application, ideal for extracting code that you want to run before navigating to a particular route.
+
+::alert{type=info}
+Route middleware run within the Vue part of your Nuxt app. Despite the similar name, they are completely different from server middleware, which are run in the Nitro server part of your app.
+::
+
+There are three kinds of route middleware:
+
+1. Anonymous (or inline) route middleware, which are defined directly in the pages where they are used.
+2. Named route middleware, which are placed in the `middleware/` directory and will be automatically loaded via asynchronous import when used on a page. (**Note**: The route middleware name is normalized to kebab-case, so `someMiddleware` becomes `some-middleware`.)
+3. Global route middleware, which are placed in the `middleware/` directory (with a `.global` suffix) and will be automatically run on every route change.
+
+Example of an `auth` middleware protecting the `/dashboard` page:
+
+::code-group
+
+```ts [middleware/auth.ts]
+export default defineNuxtRouteMiddleware((to, from) => {
+  // isAuthenticated() is an example method verifying if an user is authenticated
+  if (isAuthenticated() === false) {
+    return navigateTo('/login')
+  }
+})
+```
+
+```html [pages/dashboard.vue]
+<script setup>
+definePageMeta({
+  middleware: 'auth'
+})
+</script>
+
+<template>
+  <h1>Welcome to your dashboard</h1>
+</template>
+```
+
+::
+
+:ReadMore{link="/guide/directory-structure/middleware"}

docs/content/2.guide/2.features/4.head-management.md → docs/content/1.getting-started/5.seo-meta.md

@@ -1,12 +1,12 @@
-# Head Management
+# SEO and Meta
 
 Out-of-the-box, Nuxt provides good default values for `charset` and `viewport` meta tags, but you can override these if you need to, as well as customize other meta tags for your site in several different ways.
 
 :ReadMore{link="/api/configuration/nuxt.config#head"}
 
 ## `useHead` Composable
 
-Within your `setup` function, you can call `useHead` with an object of meta properties with keys corresponding to meta tags: `title`, `titleTemplate`, `base`, `script`, `style`, `meta` and `link`, as well as `htmlAttrs` and `bodyAttrs`. There are also two shorthand properties, `charset` and `viewport`, which set the corresponding meta tags. Alternatively, you can pass a function returning the object for reactive metadata.
+Within your `setup` function, you can call `useHead` with an object of meta properties with keys corresponding to meta tags: `title`, `titleTemplate`, `base`, `script`, `noscript`, `style`, `meta` and `link`, as well as `htmlAttrs` and `bodyAttrs`. There are also two shorthand properties, `charset` and `viewport`, which set the corresponding meta tags. Alternatively, you can pass a function returning the object for reactive metadata.
 
 For example:
 
@@ -70,7 +70,7 @@ useHead({
 
 ## Meta Components
 
-Nuxt provides `<Title>`, `<Base>`, `<Script>`, `<Style>`, `<Meta>`, `<Link>`, `<Body>`, `<Html>` and `<Head>` components so that you can interact directly with your metadata within your component's template.
+Nuxt provides `<Title>`, `<Base>`, `<Script>`, `<NoScript>`, `<Style>`, `<Meta>`, `<Link>`, `<Body>`, `<Html>` and `<Head>` components so that you can interact directly with your metadata within your component's template.
 
 Because these component names match native HTML elements, it is very important that they are capitalized in the template.
 

docs/content/2.guide/6.going-further/7.testing.md → docs/content/1.getting-started/9.testing.md

@@ -148,7 +148,6 @@ To test the modules we create, we could set up some Nuxt apps as fixtures and te
 
 ```ts
 // nuxt.config.js
-import { defineNuxtConfig } from 'nuxt'
 import MyModule from '../../src'
 
 export default defineNuxtConfig({

docs/content/1.getting-started/index.md

@@ -1,7 +1,6 @@
 ---
 title: Get Started
 layout.aside: true
-layout.asideClass: ''
 navigation.exclusive: true
-navigation.redirect: /getting-started/quick-start
+navigation.redirect: /getting-started/introduction
 ---

docs/content/2.guide/1.concepts/4.auto-imports.md → docs/content/2.guide/1.concepts/1.auto-imports.md

@@ -15,7 +15,7 @@ Auto imports don't currently work within the [server directory](/guide/directory
 
 ## Nuxt Auto-imports
 
-Nuxt auto-imports functions and composables to perform [data fetching](/guide/features/data-fetching), get access to the [app context](/api/composables/use-nuxt-app) and [runtime config](/guide/features/runtime-config), manage [state](/guide/features/state-management) or define components and plugins.
+Nuxt auto-imports functions and composables to perform [data fetching](/getting-started/data-fetching), get access to the [app context](/api/composables/use-nuxt-app) and [runtime config](/guide/going-further/runtime-config), manage [state](/getting-started/state-management) or define components and plugins.
 
 ```vue
 <script setup>

docs/content/2.guide/1.concepts/4.server-engine.md

@@ -1,8 +1,7 @@
 # Server Engine
 
-Nuxt 3 is powered by a new server engine, code-named "Nitro".
+Nuxt 3 is powered by a new server engine, [Nitro](https://nitro.unjs.io/).
 
-This engine has many benefits:
 ::list
 
 - Cross-platform support for Node.js, Browsers, service-workers and more.

docs/content/2.guide/6.going-further/5.esm.md → docs/content/2.guide/1.concepts/7.esm.md

@@ -117,8 +117,6 @@ If you encounter these errors, the issue is almost certainly with the upstream l
 In the meantime, you can tell Nuxt not to try to import these libraries by adding them to `build.transpile`:
 
 ```js
-import { defineNuxtConfig } from 'nuxt'
-
 export default defineNuxtConfig({
   build: {
     transpile: ['sample-library']
@@ -133,8 +131,6 @@ You may find that you _also_ need to add other packages that are being imported
 In some cases, you may also need to manually alias the library to the CJS version, for example:
 
 ```js
-import { defineNuxtConfig } from 'nuxt'
-
 export default defineNuxtConfig({
   alias: {
     'sample-library': 'sample-library/dist/sample-library.cjs.js'

docs/content/2.guide/1.concepts/index.md

@@ -1,7 +1,7 @@
 ---
-title: Concepts
+title: Key Concepts
 layout.aside: true
 layout.asideClass: ''
-navigation.redirect: /guide/concepts/introduction
+navigation.redirect: /guide/concepts/auto-imports
 # navigation.collapse: true
 ---

docs/content/2.guide/3.directory-structure/3.assets.md → docs/content/2.guide/2.directory-structure/1.assets.md

@@ -16,4 +16,4 @@ The directory usually contains the following types of files:
 
 If you want to serve assets from the server, we recommend taking a look at the [`public/`](/guide/directory-structure/public) directory.
 
-::ReadMore{link="/guide/features/assets"}
+::ReadMore{link="/getting-started/assets"}

docs/content/2.guide/3.directory-structure/4.components.md → docs/content/2.guide/2.directory-structure/1.components.md

@@ -70,7 +70,6 @@ If you are using `resolveComponent` to handle dynamic components, make sure not
 Alternatively, though not recommended, you can register all your components globally, which will create async chunks for all your components and make them available throughout your application.
 
 ```diff
-  import { defineNuxtConfig } from 'nuxt'
 
   export default defineNuxtConfig({
     components: {
@@ -187,7 +186,7 @@ Make sure not to _nest_ `<ClientOnly>` components or other client-only component
 If a component is meant to be rendered only client-side, you can add the `.client` suffix to your component.
 
 ```bash
-| components/ 
+| components/
 --| Comments.client.vue
 ```
 
@@ -209,14 +208,14 @@ This feature only works with Nuxt auto-imports. Explicitly importing these compo
 `.server` components are fallback components of `.client` components.
 
 ```bash
-| components/ 
+| components/
 --| Comments.client.vue
 --| Comments.server.vue
 ```
 
 ```html{}[pages/example.vue]
 <template>
-  <div> 
+  <div>
     <!-- this component will render Comments.server server-side then Comments.client once mounted in client-side -->
     <Comments />
   </div>

docs/content/2.guide/3.directory-structure/5.composables.md → docs/content/2.guide/2.directory-structure/1.composables.md

@@ -8,7 +8,7 @@ head.title: Composables Directory
 
 Nuxt 3 supports `composables/` directory to automatically import your Vue composables into your application using [auto-imports](/guide/concepts/auto-imports)!
 
-Under the hood, Nuxt auto generates the file `.nuxt/auto-imports.d.ts` to declare the types.
+Under the hood, Nuxt auto generates the file `.nuxt/imports.d.ts` to declare the types.
 
 Be aware that you have to run `nuxi prepare`, `nuxi dev` or `nuxi build` in order to let Nuxt generates the types. If you create a composable without having the dev server running, typescript will throw an error `Cannot find name 'useBar'.`
 

docs/content/2.guide/3.directory-structure/6.content.md → docs/content/2.guide/2.directory-structure/1.content.md

@@ -42,8 +42,6 @@ Install the `@nuxt/content` module in your project:
 Then, add `@nuxt/content` to the `modules` section of `nuxt.config.ts`:
 
 ```ts [nuxt.config.ts]
-import { defineNuxtConfig } from 'nuxt'
-
 export default defineNuxtConfig({
   modules: [
     '@nuxt/content'

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

@@ -53,9 +53,6 @@ Unlike navigation guards in [the vue-router docs](https://router.vuejs.org/guide
 ::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/2.guide/3.directory-structure/10.pages.md → docs/content/2.guide/2.directory-structure/1.pages.md

@@ -327,7 +327,7 @@ Learn more about [`<NuxtLink>`](/api/components/nuxt-link) usage.
 
 ## Router Options
 
-It is possible to cutomize [vue-router options](https://router.vuejs.org/api/interfaces/routeroptions.html).
+It is possible to customize [vue-router options](https://router.vuejs.org/api/interfaces/routeroptions.html).
 
 ### Using `app/router.options`
 
@@ -343,8 +343,6 @@ export default <RouterOptions> {
 
 #### Custom Routes
 
-:StabilityEdge{title="custom routes"}
-
 You can optionally override routes using a function that accepts scanned routes and returns customized routes.
 If returning `null` or `undefined`, Nuxt will fallback to the default routes. (useful to modify input array)
 
@@ -356,7 +354,7 @@ export default <RouterOptions> {
   routes: (_routes) => [
     {
       name: 'home',
-      route: '/',
+      path: '/',
       component: () => import('~/pages/home.vue')
     }
   ],
@@ -365,8 +363,6 @@ export default <RouterOptions> {
 
 #### Custom History (advanced)
 
-:StabilityEdge{title="custom history"}
-
 You can optionally override history mode using a function that accepts base url and returns history mode.
 If returning `null` or `undefined`, Nuxt will fallback to the default history.
 
@@ -402,13 +398,9 @@ export default defineNuxtConfig({
 
 ### Hash Mode (SPA)
 
-:StabilityEdge{title="hash mode"}
-
 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**.
 
 ```ts [nuxt.config.ts]
-import { defineNuxtConfig } from 'nuxt'
-
 export default defineNuxtConfig({
   ssr: false,
   router: {