Docs clean up: delete defining-routes.mdx and pages.mdx (#73863)

Please merge this PR first: #73859 Closes: - https://linear.app/vercel/issue/DOC-4050/delete-routingdefining-routesmdx - https://linear.app/vercel/issue/DOC-4051/delete-routingpagesmdx The content for this page has already been moved to the Getting Started section or API Reference.
vercel · Dec 13, 2024 · 7a124bc · 7a124bc
1 parent 26e8b76
commit 7a124bc
Show file tree

Hide file tree

Showing 16 changed files with 25 additions and 143 deletions.
diff --git a/docs/01-app/03-building-your-application/01-routing/01-defining-routes.mdx b/docs/01-app/03-building-your-application/01-routing/01-defining-routes.mdx
diff --git a/docs/01-app/03-building-your-application/01-routing/02-pages.mdx b/docs/01-app/03-building-your-application/01-routing/02-pages.mdx
diff --git a/docs/01-app/03-building-your-application/01-routing/03-layouts-and-templates.mdx b/docs/01-app/03-building-your-application/01-routing/03-layouts-and-templates.mdx
@@ -3,7 +3,7 @@ title: Layouts and Templates
 description: Create your first shared layout in Next.js.
 ---
 
-The special files [layout.js](#layouts) and [template.js](#templates) allow you to create UI that is shared between [routes](/docs/app/building-your-application/routing/defining-routes#creating-routes). This page will guide you through how and when to use these special files.
+The special files [layout.js](#layouts) and [template.js](#templates) allow you to create UI that is shared between routes. This page will guide you through how and when to use these special files.
 
 ## Layouts
 

diff --git a/docs/01-app/03-building-your-application/01-routing/13-route-handlers.mdx b/docs/01-app/03-building-your-application/01-routing/13-route-handlers.mdx
@@ -271,8 +271,6 @@ export async function GET(request) {
 
 ### Dynamic Route Segments
 
-> We recommend reading the [Defining Routes](/docs/app/building-your-application/routing/defining-routes) page before continuing.
-
 Route Handlers can use [Dynamic Segments](/docs/app/building-your-application/routing/dynamic-routes) to create request handlers from dynamic data.
 
 ```ts filename="app/items/[slug]/route.ts" switcher

diff --git a/docs/01-app/03-building-your-application/01-routing/14-middleware.mdx b/docs/01-app/03-building-your-application/01-routing/14-middleware.mdx
@@ -215,7 +215,7 @@ The `NextResponse` API allows you to:
 
 To produce a response from Middleware, you can:
 
-1. `rewrite` to a route ([Page](/docs/app/building-your-application/routing/pages) or [Route Handler](/docs/app/building-your-application/routing/route-handlers)) that produces a response
+1. `rewrite` to a route ([Page](/docs/app/api-reference/file-conventions/page) or [Route Handler](/docs/app/building-your-application/routing/route-handlers)) that produces a response
 2. return a `NextResponse` directly. See [Producing a Response](#producing-a-response)
 
 </AppOnly>

diff --git a/docs/01-app/03-building-your-application/03-rendering/04-partial-prerendering.mdx b/docs/01-app/03-building-your-application/03-rendering/04-partial-prerendering.mdx
@@ -31,7 +31,7 @@ To prevent creating many HTTP requests for each dynamic component, PPR is able t
 
 ### Incremental Adoption (Version 15)
 
-In Next.js 15, you can incrementally adopt Partial Prerendering in [layouts](/docs/app/building-your-application/routing/layouts-and-templates) and [pages](/docs/app/building-your-application/routing/pages) by setting the [`ppr`](/docs/app/api-reference/config/next-config-js/ppr) option in `next.config.js` to `incremental`, and exporting the `experimental_ppr` [route config option](/docs/app/api-reference/file-conventions/route-segment-config) at the top of the file:
+In Next.js 15, you can incrementally adopt Partial Prerendering in [layouts](/docs/app/building-your-application/routing/layouts-and-templates) and [pages](/docs/app/api-reference/file-conventions/page) by setting the [`ppr`](/docs/app/api-reference/config/next-config-js/ppr) option in `next.config.js` to `incremental`, and exporting the `experimental_ppr` [route config option](/docs/app/api-reference/file-conventions/route-segment-config) at the top of the file:
 
 ```ts filename="next.config.ts" switcher
 import type { NextConfig } from 'next'

diff --git a/docs/01-app/03-building-your-application/06-optimizing/03-fonts.mdx b/docs/01-app/03-building-your-application/06-optimizing/03-fonts.mdx
@@ -618,7 +618,7 @@ You can now use the `font-sans` and `font-mono` utility classes to apply the fon
 <AppOnly>
 When a font function is called on a page of your site, it is not globally available and preloaded on all routes. Rather, the font is only preloaded on the related routes based on the type of file where it is used:
 
-- If it's a [unique page](/docs/app/building-your-application/routing/pages), it is preloaded on the unique route for that page.
+- If it's a [unique page](/docs/app/api-reference/file-conventions/page), it is preloaded on the unique route for that page.
 - If it's a [layout](/docs/app/building-your-application/routing/layouts-and-templates#layouts), it is preloaded on all the routes wrapped by the layout.
 - If it's the [root layout](/docs/app/building-your-application/routing/layouts-and-templates#root-layout-required), it is preloaded on all routes.
 

diff --git a/docs/01-app/03-building-your-application/06-optimizing/05-scripts.mdx b/docs/01-app/03-building-your-application/06-optimizing/05-scripts.mdx
@@ -125,7 +125,7 @@ Refer to the [`next/script`](/docs/app/api-reference/components/script#strategy)
 
 ### Offloading Scripts To A Web Worker (experimental)
 
-> **Warning:** The `worker` strategy is not yet stable and does not yet work with the [`app`](/docs/app/building-your-application/routing/defining-routes) directory. Use with caution.
+> **Warning:** The `worker` strategy is not yet stable and does not yet work with the App Router. Use with caution.
 
 Scripts that use the `worker` strategy are offloaded and executed in a web worker with [Partytown](https://partytown.builder.io/). This can improve the performance of your site by dedicating the main thread to the rest of your application code.
 

diff --git a/docs/01-app/03-building-your-application/11-upgrading/05-app-router-migration.mdx b/docs/01-app/03-building-your-application/11-upgrading/05-app-router-migration.mdx
@@ -105,7 +105,7 @@ Moving to the App Router may be the first time using React features that Next.js
 We recommend reducing the combined complexity of these updates by breaking down your migration into smaller steps. The `app` directory is intentionally designed to work simultaneously with the `pages` directory to allow for incremental page-by-page migration.
 
 - The `app` directory supports nested routes _and_ layouts. [Learn more](/docs/app/building-your-application/routing).
-- Use nested folders to [define routes](/docs/app/building-your-application/routing/defining-routes) and a special `page.js` file to make a route segment publicly accessible. [Learn more](#step-4-migrating-pages).
+- Use nested folders to define routes and a special `page.js` file to make a route segment publicly accessible. [Learn more](#step-4-migrating-pages).
 - [Special file conventions](/docs/app/api-reference/file-conventions) are used to create UI for each route segment. The most common special files are `page.js` and `layout.js`.
   - Use `page.js` to define UI unique to a route.
   - Use `layout.js` to define UI that is shared across multiple routes.
@@ -327,7 +327,7 @@ export default function Page() {
 
 - Pages in the [`app` directory](/docs/app/building-your-application/routing) are [Server Components](/docs/app/building-your-application/rendering/server-components) by default. This is different from the `pages` directory where pages are [Client Components](/docs/app/building-your-application/rendering/client-components).
 - [Data fetching](/docs/app/building-your-application/data-fetching) has changed in `app`. `getServerSideProps`, `getStaticProps` and `getInitialProps` have been replaced with a simpler API.
-- The `app` directory uses nested folders to [define routes](/docs/app/building-your-application/routing/defining-routes) and a special `page.js` file to make a route segment publicly accessible.
+- The `app` directory uses nested folders to define routes and a special `page.js` file to make a route segment publicly accessible.
 - | `pages` Directory | `app` Directory       | Route          |
   | ----------------- | --------------------- | -------------- |
   | `index.js`        | `page.js`             | `/`            |

diff --git a/docs/01-app/03-building-your-application/11-upgrading/06-from-create-react-app.mdx b/docs/01-app/03-building-your-application/11-upgrading/06-from-create-react-app.mdx
@@ -306,7 +306,7 @@ On Next.js you declare an entrypoint for your application by creating a `page.ts
 
 Since this guide is aiming to first set up our Next.js as an SPA (Single Page Application), you need your page entry point to catch all possible routes of your application. For that, create a new `[[...slug]]` directory in your `app` directory.
 
-This directory is what is called an [optional catch-all route segment](/docs/app/building-your-application/routing/dynamic-routes#optional-catch-all-segments). Next.js uses a file-system based router where [directories are used to define routes](/docs/app/building-your-application/routing/defining-routes#creating-routes). This special directory will make sure that all routes of your application will be directed to its containing `page.tsx` file.
+This directory is what is called an [optional catch-all route segment](/docs/app/building-your-application/routing/dynamic-routes#optional-catch-all-segments). Next.js uses a file-system based router where folders are used to define routes. This special directory will make sure that all routes of your application will be directed to its containing `page.tsx` file.
 
 **Create a new `page.tsx` file inside the `app/[[...slug]]` directory with the following content:**
 

diff --git a/docs/01-app/03-building-your-application/11-upgrading/07-from-vite.mdx b/docs/01-app/03-building-your-application/11-upgrading/07-from-vite.mdx
@@ -349,16 +349,9 @@ entrypoint of your application.
 
 1. **Create a `[[...slug]]` directory in your `app` directory.**
 
-Since in this guide we're aiming first to set up our Next.js as an SPA (Single Page Application),
-you need your page entrypoint to catch all possible routes of your application. For that, create a
-new `[[...slug]]` directory in your `app` directory.
-
-This directory is what is called an
-[optional catch-all route segment](/docs/app/building-your-application/routing/dynamic-routes#optional-catch-all-segments).
-Next.js uses a file-system based router where
-[directories are used to define routes](/docs/app/building-your-application/routing/defining-routes#creating-routes).
-This special directory will make sure that all routes of your application will be directed to its
-containing `page.tsx` file.
+Since in this guide we're aiming first to set up our Next.js as an SPA (Single Page Application), you need your page entrypoint to catch all possible routes of your application. For that, create a new `[[...slug]]` directory in your `app` directory.
+
+This directory is what is called an [optional catch-all route segment](/docs/app/building-your-application/routing/dynamic-routes#optional-catch-all-segments). Next.js uses a file-system based router where folders are used to define routes. This special directory will make sure that all routes of your application will be directed to its containing `page.tsx` file.
 
 2. **Create a new `page.tsx` file inside the `app/[[...slug]]` directory with the following content:**
 

diff --git a/docs/01-app/04-api-reference/02-components/link.mdx b/docs/01-app/04-api-reference/02-components/link.mdx
@@ -227,7 +227,7 @@ export default function Home() {
 
 ### `scroll`
 
-**Defaults to `true`.** The default scrolling behavior of `<Link>` in Next.js **is to maintain scroll position**, similar to how browsers handle back and forwards navigation. When you navigate to a new [Page](/docs/app/building-your-application/routing/pages), scroll position will stay the same as long as the Page is visible in the viewport. However, if the Page is not visible in the viewport, Next.js will scroll to the top of the first Page element.
+**Defaults to `true`.** The default scrolling behavior of `<Link>` in Next.js **is to maintain scroll position**, similar to how browsers handle back and forwards navigation. When you navigate to a new [Page](/docs/app/api-reference/file-conventions/page), scroll position will stay the same as long as the Page is visible in the viewport. However, if the Page is not visible in the viewport, Next.js will scroll to the top of the first Page element.
 
 When `scroll = {false}`, Next.js will not attempt to scroll to the first Page element.
 
@@ -595,7 +595,7 @@ If you'd like to scroll to a specific `id` on navigation, you can append your UR
 
 > **Good to know**:
 >
-> - Next.js will scroll to the [Page](/docs/app/building-your-application/routing/pages) if it is not visible in the viewport upon navigation.
+> - Next.js will scroll to the [Page](/docs/app/api-reference/file-conventions/page) if it is not visible in the viewport upon navigation.
 
 </AppOnly>
 
@@ -1015,7 +1015,7 @@ export default function Home() {
 
 <AppOnly>
 
-The default scrolling behavior of `<Link>` in Next.js **is to maintain scroll position**, similar to how browsers handle back and forwards navigation. When you navigate to a new [Page](/docs/app/building-your-application/routing/pages), scroll position will stay the same as long as the Page is visible in the viewport.
+The default scrolling behavior of `<Link>` in Next.js **is to maintain scroll position**, similar to how browsers handle back and forwards navigation. When you navigate to a new [Page](/docs/app/api-reference/file-conventions/page), scroll position will stay the same as long as the Page is visible in the viewport.
 
 However, if the Page is not visible in the viewport, Next.js will scroll to the top of the first Page element. If you'd like to disable this behavior, you can pass `scroll={false}` to the `<Link>` component, or `scroll: false` to `router.push()` or `router.replace()`.
 

diff --git a/docs/01-app/04-api-reference/02-components/script.mdx b/docs/01-app/04-api-reference/02-components/script.mdx
@@ -208,7 +208,7 @@ Examples of scripts that do not need to load immediately and can be fetched with
 
 ### `worker`
 
-> **Warning:** The `worker` strategy is not yet stable and does not yet work with the [`app`](/docs/app/building-your-application/routing/defining-routes) directory. Use with caution.
+> **Warning:** The `worker` strategy is not yet stable and does not yet work with the App Router. Use with caution.
 
 Scripts that use the `worker` strategy are off-loaded to a web worker in order to free up the main thread and ensure that only critical, first-party resources are processed on it. While this strategy can be used for any script, it is an advanced use case that is not guaranteed to support all third-party scripts.
 

diff --git a/docs/01-app/04-api-reference/03-file-conventions/layout.mdx b/docs/01-app/04-api-reference/03-file-conventions/layout.mdx
@@ -53,7 +53,7 @@ export default function RootLayout({ children }) {
 
 #### `children` (required)
 
-Layout components should accept and use a `children` prop. During rendering, `children` will be populated with the route segments the layout is wrapping. These will primarily be the component of a child [Layout](/docs/app/building-your-application/routing/pages) (if it exists) or [Page](/docs/app/building-your-application/routing/pages), but could also be other special files like [Loading](/docs/app/building-your-application/routing/loading-ui-and-streaming) or [Error](/docs/app/building-your-application/routing/error-handling) when applicable.
+Layout components should accept and use a `children` prop. During rendering, `children` will be populated with the route segments the layout is wrapping. These will primarily be the component of a child [Layout](/docs/app/api-reference/file-conventions/page) (if it exists) or [Page](/docs/app/api-reference/file-conventions/page), but could also be other special files like [Loading](/docs/app/building-your-application/routing/loading-ui-and-streaming) or [Error](/docs/app/building-your-application/routing/error-handling) when applicable.
 
 #### `params` (optional)
 

diff --git a/docs/01-app/04-api-reference/03-file-conventions/page.mdx b/docs/01-app/04-api-reference/03-file-conventions/page.mdx
@@ -3,7 +3,7 @@ title: page.js
 description: API reference for the page.js file.
 ---
 
-The `page` file is used to define a page in your Next.js application.
+The `page` file allows you to define UI that is **unique** to a route. You can create a page by default exporting a component from the file:
 
 ```tsx filename="app/blog/[slug]/page.tsx" switcher
 export default function Page({
@@ -23,6 +23,13 @@ export default function Page({ params, searchParams }) {
 }
 ```
 
+## Good to know
+
+- The `.js`, `.jsx`, or `.tsx` file extensions can be used for `page`.
+- A `page` is always the **leaf** of the route subtree.
+- A `page` file is required to make a route segment **publicly accessible**.
+- Pages are [Server Components](https://react.dev/reference/rsc/server-components) by default, but can be set to a [Client Component](https://react.dev/reference/rsc/use-client).
+
 ## Reference
 
 ### Props

diff --git a/docs/01-app/04-api-reference/05-config/01-next-config-js/ppr.mdx b/docs/01-app/04-api-reference/05-config/01-next-config-js/ppr.mdx
@@ -14,7 +14,7 @@ Partial Prerendering (PPR) enables you to combine static and dynamic components
 
 ### Incremental Adoption (Version 15)
 
-In Next.js 15, you can incrementally adopt Partial Prerendering in [layouts](/docs/app/building-your-application/routing/layouts-and-templates) and [pages](/docs/app/building-your-application/routing/pages) by setting the [`ppr`](/docs/app/api-reference/config/next-config-js/ppr) option in `next.config.js` to `incremental`, and exporting the `experimental_ppr` [route config option](/docs/app/api-reference/file-conventions/route-segment-config) at the top of the file:
+In Next.js 15, you can incrementally adopt Partial Prerendering in [layouts](/docs/app/building-your-application/routing/layouts-and-templates) and [pages](/docs/app/api-reference/file-conventions/page) by setting the [`ppr`](/docs/app/api-reference/config/next-config-js/ppr) option in `next.config.js` to `incremental`, and exporting the `experimental_ppr` [route config option](/docs/app/api-reference/file-conventions/route-segment-config) at the top of the file:
 
 ```ts filename="next.config.ts" switcher
 import type { NextConfig } from 'next'