Clarify rewrites and other docs cleanup. (vercel#24890)

Based on user feedback, this clarifies the difference between rewrites and redirects, as well as follows the new pattern for showing version history with a collapsible table.

Author: leerob

docs/api-reference/next.config.js/basepath.md

@@ -4,7 +4,14 @@ description: Learn more about setting a base path in Next.js
 
 # Base Path
 
-> This feature was introduced in [Next.js 9.5](https://nextjs.org/blog/next-9-5) and up. If you’re using older versions of Next.js, please upgrade before trying it out.
+<details>
+  <summary><b>Version History</b></summary>
+
+| Version  | Changes          |
+| -------- | ---------------- |
+| `v9.5.0` | Base Path added. |
+
+</details>
 
 To deploy a Next.js application under a sub-path of a domain you can use the `basePath` config option.
 

docs/api-reference/next.config.js/headers.md

@@ -4,8 +4,6 @@ description: Add custom HTTP headers to your Next.js app.
 
 # Headers
 
-> This feature was introduced in [Next.js 9.5](https://nextjs.org/blog/next-9-5) and up. If you’re using older versions of Next.js, please upgrade before trying it out.
-
 <details open>
   <summary><b>Examples</b></summary>
   <ul>
@@ -16,9 +14,10 @@ description: Add custom HTTP headers to your Next.js app.
 <details>
   <summary><b>Version History</b></summary>
 
-| Version   | Changes      |
-| --------- | ------------ |
-| `v10.2.0` | `has` added. |
+| Version   | Changes        |
+| --------- | -------------- |
+| `v10.2.0` | `has` added.   |
+| `v9.5.0`  | Headers added. |
 
 </details>
 

docs/api-reference/next.config.js/redirects.md

@@ -4,8 +4,6 @@ description: Add redirects to your Next.js app.
 
 # Redirects
 
-> This feature was introduced in [Next.js 9.5](https://nextjs.org/blog/next-9-5) and up. If you’re using older versions of Next.js, please upgrade before trying it out.
-
 <details open>
   <summary><b>Examples</b></summary>
   <ul>
@@ -16,9 +14,10 @@ description: Add redirects to your Next.js app.
 <details>
   <summary><b>Version History</b></summary>
 
-| Version   | Changes      |
-| --------- | ------------ |
-| `v10.2.0` | `has` added. |
+| Version   | Changes          |
+| --------- | ---------------- |
+| `v10.2.0` | `has` added.     |
+| `v9.5.0`  | Redirects added. |
 
 </details>
 

docs/api-reference/next.config.js/rewrites.md

@@ -4,8 +4,6 @@ description: Add rewrites to your Next.js app.
 
 # Rewrites
 
-> This feature was introduced in [Next.js 9.5](https://nextjs.org/blog/next-9-5) and up. If you’re using older versions of Next.js, please upgrade before trying it out.
-
 <details open>
   <summary><b>Examples</b></summary>
   <ul>
@@ -16,14 +14,17 @@ description: Add rewrites to your Next.js app.
 <details>
   <summary><b>Version History</b></summary>
 
-| Version   | Changes      |
-| --------- | ------------ |
-| `v10.2.0` | `has` added. |
+| Version   | Changes         |
+| --------- | --------------- |
+| `v10.2.0` | `has` added.    |
+| `v9.5.0`  | Rewrites added. |
 
 </details>
 
 Rewrites allow you to map an incoming request path to a different destination path.
 
+Rewrites act as a URL proxy and mask the destination path, making it appear the user hasn't changed their location on the site. In contrast, [redirects](/docs/api-reference/next.config.js/redirects.md) will reroute to a new page a show the URL changes.
+
 Rewrites are only available on the Node.js environment and do not affect client-side routing.
 
 To use rewrites you can use the `rewrites` key in `next.config.js`:
@@ -326,7 +327,7 @@ module.exports = {
 }
 ```
 
-See additional information on incremental adoption [in the docs here](https://nextjs.org/docs/migrating/incremental-adoption).
+See additional information on incremental adoption [in the docs here](/docs/migrating/incremental-adoption.md).
 
 ### Rewrites with basePath support
 

docs/api-reference/next.config.js/trailing-slash.md

@@ -4,7 +4,14 @@ description: Configure Next.js pages to resolve with or without a trailing slash
 
 # Trailing Slash
 
-> This feature was introduced in [Next.js 9.5](https://nextjs.org/blog/next-9-5) and up. If you’re using older versions of Next.js, please upgrade before trying it out.
+<details>
+  <summary><b>Version History</b></summary>
+
+| Version  | Changes               |
+| -------- | --------------------- |
+| `v9.5.0` | Trailing Slash added. |
+
+</details>
 
 By default Next.js will redirect urls with trailing slashes to their counterpart without a trailing slash. For example `/about/` will redirect to `/about`. You can configure this behavior to act the opposite way, where urls without trailing slashes are redirected to their counterparts with trailing slashes.
 

docs/basic-features/data-fetching.md

@@ -222,20 +222,27 @@ export default Blog
 
 ### Incremental Static Regeneration
 
-> This feature was introduced in [Next.js 9.5](https://nextjs.org/blog/next-9-5#stable-incremental-static-regeneration) and up. If you’re using older versions of Next.js, please upgrade before trying Incremental Static Regeneration.
-
 <details open>
   <summary><b>Examples</b></summary>
   <ul>
-    <li><a href="https://reactions-demo.vercel.app/">Static Reactions Demo</a></li>
+    <li><a href="https://nextjs.org/commerce">Next.js Commerce</a></li>
+    <li><a href="https://reactions-demo.vercel.app/">GitHub Reactions Demo</a></li>
+    <li><a href="https://static-tweet.vercel.app/">Static Tweet Demo</a></li>
   </ul>
 </details>
 
-With [`getStaticProps`](#getstaticprops-static-generation) you don't have to stop relying on dynamic content, as **static content can also be dynamic**. Incremental Static Regeneration allows you to update _existing_ pages by re-rendering them in the background as traffic comes in.
+<details>
+  <summary><b>Version History</b></summary>
+
+| Version  | Changes          |
+| -------- | ---------------- |
+| `v9.5.0` | Base Path added. |
 
-Inspired by [stale-while-revalidate](https://tools.ietf.org/html/rfc5861), background regeneration ensures traffic is served uninterruptedly, always from static storage, and the newly built page is pushed only after it's done generating.
+</details>
 
-Consider our previous [`getStaticProps` example](#simple-example), but now with regeneration enabled:
+Next.js allows you to create or update static pages _after_ you’ve built your site. Incremental Static Regeneration (ISR) enables you to use static-generation on a per-page basis, **without needing to rebuild the entire site**. With ISR, you can retain the benefits of static while scaling to millions of pages.
+
+Consider our previous [`getStaticProps` example](#simple-example), but now with Incremental Static Regeneration enabled through the `revalidate` property:
 
 ```jsx
 function Blog({ posts }) {
@@ -261,25 +268,42 @@ export async function getStaticProps() {
     },
     // Next.js will attempt to re-generate the page:
     // - When a request comes in
-    // - At most once every second
-    revalidate: 1, // In seconds
+    // - At most once every 10 seconds
+    revalidate: 10, // In seconds
   }
 }
 
+// This function gets called at build time on server-side.
+// It may be called again, on a serverless function, if
+// the path has not been generated.
+export async function getStaticPaths() {
+  const res = await fetch('https://.../posts')
+  const posts = await res.json()
+
+  // Get the paths we want to pre-render based on posts
+  const paths = posts.map((post) => ({
+    params: { id: post.id },
+  }))
+
+  // We'll pre-render only these paths at build time.
+  // { fallback: blocking } will server-render pages
+  // on-demand if the path doesn't exist.
+  return { paths, fallback: 'blocking' }
+}
+
 export default Blog
 ```
 
-Now the list of blog posts will be revalidated once per second; if you add a new blog post it will be available almost immediately, without having to re-build your app or make a new deployment.
-
-This works perfectly with [`fallback: true`](#fallback-true). Because now you can have a list of posts that's always up to date with the latest posts, and have a [blog post page](#fallback-pages) that generates blog posts on-demand, no matter how many posts you add or update.
+When a request is made to a page that was pre-rendered at build time, it will initially show the cached page.
 
-#### Static content at scale
+- Any requests to the page after the initial request and before 10 seconds are also cached and instantaneous.
+- After the 10-second window, the next request will still show the cached (stale) page
+- Next.js triggers a regeneration of the page in the background.
+- Once the page has been successfully generated, Next.js will invalidate the cache and show the updated product page. If the background regeneration fails, the old page remains unaltered.
 
-Unlike traditional SSR, [Incremental Static Regeneration](#incremental-static-regeneration) ensures you retain the benefits of static:
+When a request is made to a path that hasn’t been generated, Next.js will server-render the page on the first request. Future requests will serve the static file from the cache.
 
-- No spikes in latency. Pages are served consistently fast
-- Pages never go offline. If the background page re-generation fails, the old page remains unaltered
-- Low database and backend load. Pages are re-computed at most once concurrently
+To learn how to persist the cache globally and handle rollbacks, learn more about [Incremental Static Regeneration](https://vercel.com/docs/next.js/incremental-static-regeneration).
 
 ### Reading files: Use `process.cwd()`