Backport documentation fixes for 16.1.x (#90655)

## Summary

Backports documentation fixes and improvements from canary to the
`next-16-1` branch.

### Included commits:
- `757ab17e54` In-Depth Explanation of React Version Handling Doc
(#89426)
- `fe0bb2fc51` Next.js sticky scroll standards (#90197)
- `d13d1ba23b` docs: improve form guide consistency and validation
examples (#90361)
- `c23f3434a3` docs: fixes typo in manifest.mdx regarding Route Handler
note (#90394)
- `dcf11d111b` docs: clarify that next upgrade is for 16.1.x+ (#90435)
- `da0cbcce76` Add not-found.js / notFound() links to Status Codes
section (#88332)
- `ae79ae55eb` docs: add Docker Standalone and Docker Export examples to
Deploying page (#90386)
- `bb813afd49` docs(deploying): add Hostinger Web Apps Hosting to
Node.js deployment options (#90246)
- `15fcfb9ce4` docs: fix navigationType value and variable name in
useReportWebVitals (#90599)
- `080e1b3` docs: Accept header content negotiation (#90607)

---------

Co-authored-by: Abhishek Mardiya <[email protected]>
Co-authored-by: vercel[bot] <35613825+vercel[bot]@users.noreply.github.com>
Co-authored-by: Jimmy Lai <[email protected]>
Co-authored-by: Cursor Agent <[email protected]>
Co-authored-by: Mary Lavanitha <[email protected]>
Co-authored-by: Tyler Arthur <[email protected]>
Co-authored-by: Karl Horky <[email protected]>
Co-authored-by: Kristiyan Velkov <[email protected]>
Co-authored-by: Wyatt Johnson <[email protected]>
Co-authored-by: kristiyan.velkov <[email protected]>
Co-authored-by: agneliutkiene <[email protected]>
Co-authored-by: Mimori <[email protected]>
Co-authored-by: Joseph <[email protected]>

Author: 13 people

docs/01-app/01-getting-started/01-installation.mdx

@@ -126,7 +126,10 @@ yarn add next@latest react@latest react-dom@latest
 bun add next@latest react@latest react-dom@latest
 ```
 
-> **Good to know**: The App Router uses [React canary releases](https://react.dev/blog/2023/05/03/react-canaries) built-in, which include all the stable React 19 changes, as well as newer features being validated in frameworks. The Pages Router uses the React version you install in `package.json`.
+> **Good to know**:
+>
+> - The `App Router` uses [React canary releases](https://react.dev/blog/2023/05/03/react-canaries) built-in, which include all the stable React 19 changes, as well as newer features being validated in frameworks, but you should still declare react and react-dom in package.json for tooling and ecosystem compatibility.
+> - The `Pages Router` uses the React version from your `package.json`.
 
 Then, add the following scripts to your `package.json` file:
 

docs/01-app/01-getting-started/04-linking-and-navigating.mdx

@@ -158,6 +158,8 @@ Next.js avoids this with client-side transitions using the `<Link>` component. I
 
 Client-side transitions are what makes a server-rendered apps _feel_ like client-rendered apps. And when paired with [prefetching](#prefetching) and [streaming](#streaming), it enables fast transitions, even for dynamic routes.
 
+Next.js also handles [scrolling to the top of the page](/docs/app/api-reference/components/link#scroll) during client-side transitions. If content scrolls behind a sticky or fixed header after navigation, you can fix this with CSS [`scroll-padding-top`](/docs/app/api-reference/components/link#scroll-offset-with-sticky-headers).
+
 ## What can make transitions slow?
 
 These Next.js optimizations make navigation fast and responsive. However, under certain conditions, transitions can still _feel_ slow. Here are some common causes and how to improve the user experience:

docs/01-app/01-getting-started/17-deploying.mdx

@@ -35,19 +35,26 @@ Node.js deployments support all Next.js features. Learn how to [configure them](
 - [Flightcontrol](https://github.com/nextjs/deploy-flightcontrol)
 - [Railway](https://github.com/nextjs/deploy-railway)
 - [Replit](https://github.com/nextjs/deploy-replit)
+- [Hostinger](https://github.com/hostinger/deploy-nextjs)
 
 ## Docker
 
-Next.js can be deployed to any provider that supports [Docker](https://www.docker.com/) containers. This includes container orchestrators like Kubernetes or a cloud provider that runs Docker.
+Next.js can be deployed to any provider that supports [Docker](https://www.docker.com/) containers. This includes container orchestrators like Kubernetes or a cloud provider that runs Docker. For containerization best practices, see the [Docker guide for React.js](https://docs.docker.com/guides/reactjs/).
 
 Docker deployments support all Next.js features. Learn how to [configure them](/docs/app/guides/self-hosting) for your infrastructure.
 
 > **Note for development:** While Docker is excellent for production deployments, consider using local development (`npm run dev`) instead of Docker during development on Mac and Windows for better performance. [Learn more about optimizing local development](/docs/app/guides/local-development).
 
 ### Templates
 
-- [Docker](https://github.com/vercel/next.js/tree/canary/examples/with-docker)
-- [Docker Multi-Environment](https://github.com/vercel/next.js/tree/canary/examples/with-docker-multi-env)
+The following examples demonstrate best practices for containerizing Next.js applications:
+
+- [Docker Standalone Output](https://github.com/vercel/next.js/tree/canary/examples/with-docker) - Deploy a Next.js application using `output: "standalone"` to generate a minimal, production-ready Docker image with only the required runtime files and dependencies.
+- [Docker Export Output](https://github.com/vercel/next.js/tree/canary/examples/with-docker-export-output) - Deploy a fully static Next.js application using `output: "export"` to generate optimized HTML files that can be served from a lightweight container or any static hosting environment.
+- [Docker Multi-Environment](https://github.com/vercel/next.js/tree/canary/examples/with-docker-multi-env) - Manage separate Docker configurations for development, staging, and production environments with different environment variables.
+
+Additionally, hosting providers offer guidance on deploying Next.js:
+
 - [DigitalOcean](https://github.com/nextjs/deploy-digitalocean)
 - [Fly.io](https://github.com/nextjs/deploy-fly)
 - [Google Cloud Run](https://github.com/nextjs/deploy-google-cloud-run)

docs/01-app/01-getting-started/18-upgrading.mdx

@@ -30,7 +30,7 @@ yarn next upgrade
 bunx next upgrade
 ```
 
-Next.js 15 and earlier do not support the `upgrade` command and need to use a separate package instead:
+Versions before Next.js 16.1.0 do not support the `upgrade` command and need to use a separate package instead:
 
 ```bash filename="Terminal"
 npx @next/codemod@canary upgrade latest

docs/01-app/02-guides/backend-for-frontend.mdx

@@ -4,10 +4,11 @@ nav_title: Backend for Frontend
 description: Learn how to use Next.js as a backend framework
 related:
   title: API Reference
-  description: Learn more about Route Handlers and Proxy
+  description: Learn more about Route Handlers, Proxy, and Rewrites
   links:
     - app/api-reference/file-conventions/route
     - app/api-reference/file-conventions/proxy
+    - app/api-reference/config/next-config-js/rewrites
 ---
 
 Next.js supports the "Backend for Frontend" pattern. This lets you create public endpoints to handle HTTP requests and return any content type—not just HTML. You can also access data sources and perform side effects like updating remote data.
@@ -178,6 +179,105 @@ export async function GET(request) {
 
 Sanitize any input used to generate markup.
 
+### Content negotiation
+
+You can use [rewrites](/docs/app/api-reference/config/next-config-js/rewrites) with header matching to serve different content types from the same URL based on the request's `Accept` header. This is known as [content negotiation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Content_negotiation).
+
+For example, a documentation site might serve HTML pages to browsers and raw Markdown to AI agents from the same `/docs/…` URLs.
+
+**1. Configure a rewrite that matches the `Accept` header:**
+
+```js filename="next.config.js"
+module.exports = {
+  async rewrites() {
+    return [
+      {
+        source: '/docs/:slug*',
+        destination: '/docs/md/:slug*',
+        has: [
+          {
+            type: 'header',
+            key: 'accept',
+            value: '(.*)text/markdown(.*)',
+          },
+        ],
+      },
+    ]
+  },
+}
+```
+
+When a request to `/docs/getting-started` includes `Accept: text/markdown`, the rewrite routes it to `/docs/md/getting-started`. A Route Handler at that path returns the Markdown response. Clients that do not send `text/markdown` in their `Accept` header continue to receive the normal HTML page.
+
+**2. Create a Route Handler for the Markdown response:**
+
+```ts filename="app/docs/md/[...slug]/route.ts" switcher
+import { getDocsMd, generateDocsStaticParams } from '@/lib/docs'
+
+export async function generateStaticParams() {
+  return generateDocsStaticParams()
+}
+
+export async function GET(_: Request, ctx: RouteContext<'/docs/md/[...slug]'>) {
+  const { slug } = await ctx.params
+  const mdDoc = await getDocsMd({ slug })
+
+  if (mdDoc == null) {
+    return new Response(null, { status: 404 })
+  }
+
+  return new Response(mdDoc, {
+    headers: {
+      'Content-Type': 'text/markdown; charset=utf-8',
+      Vary: 'Accept',
+    },
+  })
+}
+```
+
+```js filename="app/docs/md/[...slug]/route.js" switcher
+import { getDocsMd, generateDocsStaticParams } from '@/lib/docs'
+
+export async function generateStaticParams() {
+  return generateDocsStaticParams()
+}
+
+export async function GET(_, { params }) {
+  const { slug } = await params
+  const mdDoc = await getDocsMd({ slug })
+
+  if (mdDoc == null) {
+    return new Response(null, { status: 404 })
+  }
+
+  return new Response(mdDoc, {
+    headers: {
+      'Content-Type': 'text/markdown; charset=utf-8',
+      Vary: 'Accept',
+    },
+  })
+}
+```
+
+The [`Vary: Accept`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Vary) response header tells caches that the response body depends on the `Accept` request header. Without it, a shared cache could serve a cached Markdown response to a browser (or vice versa). Most hosting providers already include the `Accept` header in their cache key, but setting `Vary` explicitly ensures correct behavior across all CDNs and proxy caches.
+
+`generateStaticParams` lets you pre-render the Markdown variants at build time so they can be served from the edge without hitting the origin server on every request.
+
+**3. Test it with `curl`:**
+
+```bash
+# Returns Markdown
+curl -H "Accept: text/markdown" https://example.com/docs/getting-started
+
+# Returns the normal HTML page
+curl https://example.com/docs/getting-started
+```
+
+> **Good to know:**
+>
+> - The `/docs/md/...` route is still directly accessible without the rewrite. If you want to restrict it to only serve via the rewrite, use [`proxy`](/docs/app/api-reference/file-conventions/proxy) to block direct requests that don't include the expected `Accept` header.
+> - For more advanced negotiation logic, you can use [`proxy`](/docs/app/api-reference/file-conventions/proxy) instead of rewrites for more flexibility.
+
 ### Consuming request payloads
 
 Use Request [instance methods](https://developer.mozilla.org/en-US/docs/Web/API/Request#instance_methods) like `.json()`, `.formData()`, or `.text()` to access the request body.

docs/01-app/03-api-reference/02-components/link.mdx

@@ -884,6 +884,58 @@ export default function Home() {
 
 </PagesOnly>
 
+### Scroll offset with sticky headers
+
+Because Next.js skips sticky and fixed positioned elements when finding the scroll target, content may end up behind a sticky header after navigation. For example, if your layout has a sticky header:
+
+```tsx filename="app/layout.tsx" switcher
+import './globals.css'
+
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode
+}) {
+  return (
+    <html lang="en">
+      <body>
+        <header className="sticky top-0 h-16 bg-white">
+          {/* Navigation */}
+        </header>
+        {children}
+      </body>
+    </html>
+  )
+}
+```
+
+```jsx filename="app/layout.js" switcher
+import './globals.css'
+
+export default function RootLayout({ children }) {
+  return (
+    <html lang="en">
+      <body>
+        <header className="sticky top-0 h-16 bg-white">
+          {/* Navigation */}
+        </header>
+        {children}
+      </body>
+    </html>
+  )
+}
+```
+
+You can account for its height using [`scroll-padding-top`](https://developer.mozilla.org/en-US/docs/Web/CSS/scroll-padding-top) on the scroll container:
+
+```css filename="app/globals.css"
+html {
+  scroll-padding-top: 64px; /* Match the height of your sticky header */
+}
+```
+
+This is a browser CSS property that offsets scroll-based positioning. It applies whenever Next.js uses the native [`scrollIntoView()`](https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollIntoView) API, including hash fragment (`#id`) navigation. Alternatively, you can use [`scroll-margin-top`](https://developer.mozilla.org/en-US/docs/Web/CSS/scroll-margin-top) on individual target elements instead of setting a global offset.
+
 ### Prefetching links in Proxy
 
 It's common to use [Proxy](/docs/app/api-reference/file-conventions/proxy) for authentication or other purposes that involve rewriting the user to a different page. In order for the `<Link />` component to properly prefetch links with rewrites via Proxy, you need to tell Next.js both the URL to display and the URL to prefetch. This is required to avoid un-necessary fetches to proxy to know the correct route to prefetch.

docs/01-app/03-api-reference/03-file-conventions/01-metadata/manifest.mdx

@@ -21,7 +21,7 @@ Add or generate a `manifest.(json|webmanifest)` file that matches the [Web Manif
 
 Add a `manifest.js` or `manifest.ts` file that returns a [`Manifest` object](#manifest-object).
 
-> Good to know: `manifest.js` is special Route Handlers that is cached by default unless it uses a [Dynamic API](/docs/app/guides/caching#dynamic-apis) or [dynamic config](/docs/app/guides/caching#segment-config-options) option.
+> Good to know: `manifest.js` is a special Route Handler that is cached by default unless it uses a [Dynamic API](/docs/app/guides/caching#dynamic-apis) or [dynamic config](/docs/app/guides/caching#segment-config-options) option.
 
 ```ts filename="app/manifest.ts" switcher
 import type { MetadataRoute } from 'next'

docs/01-app/03-api-reference/03-file-conventions/not-found.mdx

@@ -10,7 +10,7 @@ Next.js provides two conventions to handle not found cases:
 
 ## `not-found.js`
 
-The **not-found** file is used to render UI when the [`notFound`](/docs/app/api-reference/functions/not-found) function is thrown within a route segment. Along with serving a custom UI, Next.js will return a `200` HTTP status code for streamed responses, and `404` for non-streamed responses.
+The **not-found** file is used to render UI when the [`notFound`](/docs/app/api-reference/functions/not-found) function is thrown within a route segment. Along with serving a custom UI, Next.js will return a `200` HTTP status code for streamed responses, and `404` for non-streamed responses (see [Status Codes](/docs/app/api-reference/file-conventions/loading#status-codes) for details about SEO).
 
 ```tsx filename="app/not-found.tsx" switcher
 import Link from 'next/link'

docs/01-app/03-api-reference/04-functions/not-found.mdx

@@ -3,7 +3,7 @@ title: notFound
 description: API Reference for the notFound function.
 ---
 
-The `notFound` function allows you to render the [`not-found file`](/docs/app/api-reference/file-conventions/not-found) within a route segment as well as inject a `<meta name="robots" content="noindex" />` tag.
+The `notFound` function allows you to render the [`not-found file`](/docs/app/api-reference/file-conventions/not-found) within a route segment as well as inject a [`<meta name="robots" content="noindex" />`](/docs/app/api-reference/file-conventions/loading#status-codes) tag for search engines.
 
 ## `notFound()`
 

docs/01-app/03-api-reference/04-functions/use-report-web-vitals.mdx

@@ -72,7 +72,7 @@ The `metric` object passed as the hook's argument consists of a number of proper
 - `name`: The name of the performance metric. Possible values include names of [Web Vitals](#web-vitals) metrics (TTFB, FCP, LCP, FID, CLS) specific to a web application.
 - `delta`: The difference between the current value and the previous value of the metric. The value is typically in milliseconds and represents the change in the metric's value over time.
 - `entries`: An array of [Performance Entries](https://developer.mozilla.org/docs/Web/API/PerformanceEntry) associated with the metric. These entries provide detailed information about the performance events related to the metric.
-- `navigationType`: Indicates the [type of navigation](https://developer.mozilla.org/docs/Web/API/PerformanceNavigationTiming/type) that triggered the metric collection. Possible values include `"navigate"`, `"reload"`, `"back_forward"`, and `"prerender"`.
+- `navigationType`: Indicates the navigation type that triggered metric collection. Values are derived from [PerformanceNavigationTiming.type](https://developer.mozilla.org/docs/Web/API/PerformanceNavigationTiming/type) and may include `"navigate"`, `"reload"`, `"prerender"`, `"back-forward"` (normalized from `"back_forward"`), `"back-forward-cache"` (BFCache restore), and `"restore"` (page restored after discard).
 - `rating`: A qualitative rating of the metric value, providing an assessment of the performance. Possible values are `"good"`, `"needs-improvement"`, and `"poor"`. The rating is typically determined by comparing the metric value against predefined thresholds that indicate acceptable or suboptimal performance.
 - `value`: The actual value or duration of the performance entry, typically in milliseconds. The value provides a quantitative measure of the performance aspect being tracked by the metric. The source of the value depends on the specific metric being measured and can come from various [Performance API](https://developer.mozilla.org/docs/Web/API/Performance_API)s.
 
@@ -183,7 +183,7 @@ You can handle all the results of these metrics separately:
 ```jsx filename="pages/_app.js"
 import { useReportWebVitals } from 'next/web-vitals'
 
-function handleCustomMetrics(metrics) {
+function handleCustomMetrics(metric) {
   switch (metric.name) {
     case 'Next.js-hydration':
       // handle hydration results
@@ -216,7 +216,7 @@ You can send results to any endpoint to measure and track
 real user performance on your site. For example:
 
 ```js
-function postWebVitals(metrics) {
+function postWebVitals(metric) {
   const body = JSON.stringify(metric)
   const url = 'https://example.com/analytics'