docs: small updates

.eslintrc.js

@@ -52,6 +52,8 @@ module.exports = {
             "newlines-between": "always",
           },
         ],
+
+        "react/jsx-no-leaked-render": [WARN, { validStrategies: ["ternary"] }],
       },
     },
   ],

docs/components/await.md

@@ -1,43 +1,56 @@
 ---
 title: Await
-toc: false
 ---
 
 # `<Await>`
 
-To get started with streaming data, check out the [Streaming Guide][streaming-guide-2].
+To get started with streaming data, check out the [Streaming Guide][streaming-guide].
 
-The `<Await>` component is responsible for resolving deferred loader promises accessed from [`useLoaderData`][useloaderdata].
+The `<Await>` component is responsible for resolving deferred loader promises accessed from [`useLoaderData`][use-loader-data].
 
 ```tsx
+import { defer } from "@remix-run/node"; // or cloudflare/deno
 import { Await } from "@remix-run/react";
 
-<Suspense fallback={<div>Loading...</div>}>
-  <Await resolve={somePromise}>
-    {(resolvedValue) => <p>{resolvedValue}</p>}
-  </Await>
-</Suspense>;
+export const loader = async () => {
+  return defer({
+    somePromise: new Promise((resolve) =>
+      resolve("Hello World!")
+    ),
+  });
+};
+
+export default function Component() {
+  const { somePromise } = useLoaderData<typeof loader>();
+  return (
+    <Suspense fallback={<div>Loading...</div>}>
+      <Await resolve={somePromise}>
+        {(resolvedValue) => <p>{resolvedValue}</p>}
+      </Await>
+    </Suspense>
+  );
+}
 ```
 
 ## Props
 
 ### `resolve`
 
-The resolve prop takes a promise from [`useLoaderData`][useloaderdata] to resolve when the data has streamed in.
+The resolve prop takes a promise from [`useLoaderData`][use-loader-data] to resolve when the data has streamed in.
 
 ```tsx
 <Await resolve={somePromise} />
 ```
 
-When the promise is not resolve, a parent suspense boundary's fallback will be rendered.
+When the promise is not resolved, a parent suspense boundary's fallback will be rendered.
 
 ```tsx
 <Suspense fallback={<div>Loading...</div>}>
   <Await resolve={somePromise} />
 </Suspense>
 ```
 
-When the promise is resolved, the children will be rendered.
+When the promise is resolved, the `children` will be rendered.
 
 ### `children`
 
@@ -49,7 +62,7 @@ The `children` can be a render callback or a React element.
 </Await>
 ```
 
-If the `children` props is a React element, the resolved value will be accessible through `useAsyncValue` in the subtree.
+If the `children` props is a React element, the resolved value will be accessible through [`useAsyncValue`][use-async-value] in the subtree.
 
 ```tsx
 <Await resolve={somePromise}>
@@ -74,7 +87,7 @@ The `errorElement` prop can be used to render an error boundary when the promise
 <Await errorElement={<div>Oops!</div>} />
 ```
 
-The error can be accessed in the sub tree with [`useAsyncError`][use-async-error]
+The error can be accessed in the subtree with [`useAsyncError`][use-async-error]
 
 ```tsx
 <Await errorElement={<SomeChild />} />
@@ -89,8 +102,7 @@ function SomeChild() {
 }
 ```
 
-[defer]: ../utils/defer
 [streaming-guide]: ../guides/streaming
-[useloaderdata]: ../hooks/use-loader-data
-[streaming-guide-2]: ../guides/streaming
+[use-loader-data]: ../hooks/use-loader-data
+[use-async-value]: ../hooks/use-async-value
 [use-async-error]: ../hooks/use-async-error

docs/components/form.md

@@ -11,24 +11,24 @@ import { Form } from "@remix-run/react";
 
 function NewEvent() {
   return (
-    <Form method="post" action="/events">
-      <input type="text" name="title" />
-      <input type="text" name="description" />
+    <Form action="/events" method="post">
+      <input name="title" type="text" />
+      <input name="description" type="text" />
     </Form>
   );
 }
 ```
 
 - Whether JavaScript is on the page or not, your data interactions created with `<Form>` and `action` will work.
-- After a `<Form>` submission, all the loaders on the page will be reloaded. This ensures that any updates to your data are reflected in the UI.
+- After a `<Form>` submission, all the `loader`s on the page will be reloaded. This ensures that any updates to your data are reflected in the UI.
 - `<Form>` automatically serializes your form's values (identically to the browser when not using JavaScript).
-- You can build "optimistic UI" and pending indicators with [`useNavigation`][usenavigation].
+- You can build "optimistic UI" and pending indicators with [`useNavigation`][use-navigation].
 
 ## Props
 
 ### `action`
 
-Most of the time you can omit this prop. Forms without an action prop (`<Form method="post">`) will automatically post to the same route within which they are rendered. This makes collocating your component, your data reads, and your data writes a snap.
+Most of the time you can omit this prop. `Form`s without an `action` prop (`<Form method="post">`) will automatically post to the same route within which they are rendered. This makes collocating your component, your data reads, and your data writes a snap.
 
 If you need to post to a different route, then add an action prop:
 
@@ -42,31 +42,33 @@ Because index routes and their parent route share the same URL, the `?index` par
 <Form action="/accounts?index" method="post" />
 ```
 
-| action url        | route action                     |
+| `action` url      | route action                     |
 | ----------------- | -------------------------------- |
 | `/accounts?index` | `app/routes/accounts._index.tsx` |
 | `/accounts`       | `app/routes/accounts.tsx`        |
 
 See also:
 
-- [`?index` query param][index query param]
+- [`?index` query param][index-query-param]
 
 ### `method`
 
-This determines the [HTTP verb][http-verb] to be used: get, post, put, patch, delete. The default is "get".
+This determines the [HTTP verb][http-verb] to be used: `DELETE`, `GET`, `PATCH`, `POST`, and `PUT`. The default is `GET`.
 
 ```tsx
 <Form method="post" />
 ```
 
-Native `<form>` only supports get and post, so if you want your form to work with JavaScript on or off the page you'll need to stick with those two.
+Native [`<form>`][form-element] only supports `GET` and `POST`, so if you want your form to work with JavaScript on or off the page you'll need to stick with those two.
 
-Without JavaScript, Remix will turn non-get requests into "post", but you'll still need to instruct your server with a hidden input like `<input type="hidden" name="_method" value="delete" />`. If you always include JavaScript, you don't need to worry about this.
+Without JavaScript, Remix will turn non-`GET` requests into `POST`, but you'll still need to instruct your server with a hidden input like `<input type="hidden" name="_method" value="delete" />`. If you always include JavaScript, you don't need to worry about this.
 
-We generally recommend sticking with "get" and "post" because the other verbs are not supported by HTML.
+We generally recommend sticking with `GET` and `POST` because the other verbs are not supported by HTML.
 
 ### `encType`
 
+<!-- this can also be `text/plain` -->
+
 Defaults to `application/x-www-form-urlencoded`, use `multipart/form-data` for file uploads.
 
 ### `replace`
@@ -105,16 +107,19 @@ This is recommended over `<form />`. When the `action` prop is omitted, `<Form>`
 
 **Related APIs:**
 
-- [`useNavigation`][usenavigation]
-- [`useActionData`][useactiondata]
-- [`useSubmit`][usesubmit]
+- [`useActionData`][use-action-data]
+- [`useNavigation`][use-navigation]
+- [`useSubmit`][use-submit]
+
+[use-navigation]: ../hooks/use-navigation
+
+<!-- page doesn't exist anymore -->
 
-[index query param]: ../guides/routing#what-is-the-index-query-param
-[usenavigation]: ../hooks/use-navigation
-[useactiondata]: ../hooks/use-action-data
-[usesubmit]: ../hooks/use-submit
+[index-query-param]: ../guides/routing#what-is-the-index-query-param
 [http-verb]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods
-[rr-form]: https://reactrouter.com/components/form
+[form-element]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/form
+[use-action-data]: ../hooks/use-action-data
+[use-submit]: ../hooks/use-submit
 [data-mutations-with-form-action]: https://www.youtube.com/watch?v=Iv25HAHaFDs&list=PLXoynULbYuEDG2wBFSZ66b85EIspy3fy6
 [multiple-forms-and-single-button-mutations]: https://www.youtube.com/watch?v=w2i-9cYxSdc&list=PLXoynULbYuEDG2wBFSZ66b85EIspy3fy6
 [clearing-inputs-after-form-submissions]: https://www.youtube.com/watch?v=bMLej7bg5Zo&list=PLXoynULbYuEDG2wBFSZ66b85EIspy3fy6

docs/discussion/00-introduction.md

@@ -7,7 +7,7 @@ order: 0
 
 These discussion topics are intended to be read in order. It gives you a linear path to Remix mastery instead of bouncing around from one doc to another. While useful independently, topics may refer to code and concepts from previous chapters.
 
-Built on top of [React Router][reactrouter], Remix is four things:
+Built on top of [React Router][react-router], Remix is four things:
 
 1. A compiler
 2. A server-side HTTP handler
@@ -44,7 +44,7 @@ app.all(
 );
 ```
 
-Express (or Node.js) is the actual server, Remix is just a handler on that server. The `"@remix-run/express"` package is called an adapter. Remix handlers are server agnostic. Adapters make them work for a specific server by converting the server's request/response API into the Fetch API on the way in, and then adapting the Fetch Response coming from Remix into the server's response API. Here's some pseudo code of what an adapter does:
+Express (or Node.js) is the actual server, Remix is just a handler on that server. The `"@remix-run/express"` package is called an adapter. Remix handlers are server agnostic. Adapters make them work for a specific server by converting the server's request/response API into the Fetch API on the way in, and then adapting the Fetch Response coming from Remix into the server's response API. Here's some pseudocode of what an adapter does:
 
 ```ts
 export function createRequestHandler({ build }) {
@@ -138,15 +138,15 @@ export async function action({ request }: ActionArgs) {
 
 You can actually use Remix as just a server-side framework without using any browser JavaScript at all. The route conventions for data loading with `loader`, mutations with `action` and HTML forms, and components that render at URLs, can provide the core feature set of a lot of web projects.
 
-In this way, **Remix scales down**. Not every page in your application needs a bunch of JavaScript in the browser and not every user interaction requires any extra flair than the browser's default behaviors. In Remix you can build it the simple way first, and then scale up without changing the fundamental model. Additionally, the majority of the app works before JavaScript loads in the browser, which makes Remix apps resilient to choppy network conditions by design.
+In this way, **Remix scales down**. Not every page in your application needs a bunch of JavaScript in the browser and not every user interaction requires any extra flair than the browser's default behaviors. In Remix, you can build it the simple way first, and then scale up without changing the fundamental model. Additionally, the majority of the app works before JavaScript loads in the browser, which makes Remix apps resilient to choppy network conditions by design.
 
 If you're not familiar with traditional back-end web frameworks, you can think of Remix routes as React components that are already their own API route and already know how to load and submit data to themselves on the server.
 
 ## Browser Framework
 
 Once Remix has served the document to the browser, it "hydrates" the page with the browser build's JavaScript modules. This is where we talk a lot about Remix "emulating the browser".
 
-When the user clicks a link, instead of making a round trip to the server for the entire document and all of the assets, Remix simply fetches the data for the next page and updates the UI. This has many performance benefits over making a full-document request:
+When the user clicks a link, instead of making a round trip to the server for the entire document and all the assets, Remix simply fetches the data for the next page and updates the UI. This has many performance benefits over making a full-document request:
 
 1. Assets don't need to be re-downloaded (or pulled from cache)
 2. Assets don't need to be parsed by the browser again
@@ -158,15 +158,15 @@ This approach also has UX benefits like not resetting the scroll position of a s
 
 Remix can also prefetch all resources for a page when the user is about to click a link. The browser framework knows about the compiler's asset manifest. It can match the URL of the link, read the manifest, and then prefetch all data, JavaScript modules, and even CSS resources for the next page. This is how Remix apps feel fast even when networks are slow.
 
-Remix then provides client side APIs so you can create rich user experiences without changing the fundamental model of HTML and browsers.
+Remix then provides client side APIs, so you can create rich user experiences without changing the fundamental model of HTML and browsers.
 
 Taking our route module from before, here are a few small, but useful UX improvements to the form that you can only do with JavaScript in the browser:
 
 1. Disable the button when the form is being submitted
 2. Focus the input when server-side form validation fails
 3. Animate in the error messages
 
-```tsx nocopy lines=[4-6,8-12,23-26,30-32]
+```tsx lines=[4-6,8-12,23-26,30-32] nocopy
 export default function Projects() {
   const projects = useLoaderData<typeof loader>();
   const actionData = useActionData<typeof action>();
@@ -213,7 +213,7 @@ Because Remix reaches into the controller level of the backend, it can do this s
 
 And while it doesn't reach as far back into the stack as server-side frameworks like Rails and Laravel, it does reach way farther up the stack into the browser to make the transition from the back end to the front end seamless.
 
-For example. Building a plain HTML form and server-side handler in a back-end heavy web framework is just as easy to do as it is in Remix. But as soon as you want to cross over into an experience with animated validation messages, focus management, and pending UI, it requires a fundamental change in the code. Typically people build an API route and then bring in a splash of client-side JavaScript to connect the two. With Remix you simply add some code around the existing "server side view" without changing how it works fundamentally.
+For example. Building a plain HTML form and server-side handler in a back-end heavy web framework is just as easy to do as it is in Remix. But as soon as you want to cross over into an experience with animated validation messages, focus management, and pending UI, it requires a fundamental change in the code. Typically, people build an API route and then bring in a splash of client-side JavaScript to connect the two. With Remix, you simply add some code around the existing "server side view" without changing how it works fundamentally.
 
 We borrowed an old term and called this Progressive Enhancement in Remix. Start small with a plain HTML form (Remix scales down) and then scale the UI up when you have the time and ambition.
 
@@ -224,4 +224,4 @@ We borrowed an old term and called this Progressive Enhancement in Remix. Start
 [vercel]: https://vercel.com
 [netlify]: https://netlify.com
 [arc]: https://arc.codes
-[reactrouter]: https://reactrouter.com
+[react-router]: https://reactrouter.com

docs/discussion/01-runtimes.md

@@ -11,7 +11,7 @@ Deploying a Remix application has four layers:
 3. A server adapter like `@remix-run/express`
 4. A web host or platform
 
-Depending on your web host, you may have fewer layers. For example, deploying to Cloudflare Pages takes care of 2, 3, and 4 all at once. Deploying Remix inside of an express app will have all four, and using the "Remix App Server" combines 2 and 3!
+Depending on your web host, you may have fewer layers. For example, deploying to Cloudflare Pages takes care of 2, 3, and 4 all at once. Deploying Remix inside an Express app will have all four, and using the "Remix App Server" combines 2 and 3!
 
 You can wire all of these up yourself, or start with a Remix Template.
 
@@ -49,11 +49,11 @@ import { createCookieSessionStorage } from "remix";
 
 ## Adapters
 
-Remix is not an HTTP server, but rather a handler inside of an existing HTTP server. Adapters allow the Remix handler to run inside the HTTP server. Some JavaScript runtimes, especially Node.js, have multiple ways to create an HTTP server. For example, in Node.js you can use Express.js, fastify, or raw `http.createServer`.
+Remix is not an HTTP server, but rather a handler inside an existing HTTP server. Adapters allow the Remix handler to run inside the HTTP server. Some JavaScript runtimes, especially Node.js, have multiple ways to create an HTTP server. For example, in Node.js you can use Express.js, fastify, or raw `http.createServer`.
 
 Each of these servers has its own Request/Response API. The adapter's job is to convert the incoming request to a Web Fetch Request, run the Remix handler, and then adapt the Web Fetch Response back to the host server's response API.
 
-Here's some pseudo code that illustrates the flow.
+Here's some pseudocode that illustrates the flow.
 
 ```tsx
 // import the app build created by `remix build`
@@ -92,7 +92,7 @@ See [`@remix-run/serve`][serve]
 
 ## Templates
 
-Remix is designed to be incredibly flexible with just enough opinions to connect the UI to the back end but it doesn't bring opinions on the database you use, how you cache data, or where and how your app is deployed.
+Remix is designed to be incredibly flexible with just enough opinions to connect the UI to the back end, but it doesn't bring opinions on the database you use, how you cache data, or where and how your app is deployed.
 
 Remix templates are starting points for app development with all of these extra opinions baked in, created by the community.
 
@@ -110,7 +110,7 @@ Once you've picked a template or [set up an app from scratch][quickstart], you'r
 [serve]: ../other-api/serve
 [quickstart]: ../start/quickstart
 [templates-guide]: ../guides/templates
-[remix-run-cloudflare-pages]: https://www.npmjs.com/package/@remix-run/cloudflare-pages
-[remix-run-cloudflare-workers]: https://www.npmjs.com/package/@remix-run/cloudflare-workers
-[remix-run-deno]: https://www.npmjs.com/package/@remix-run/deno
-[remix-run-node]: https://www.npmjs.com/package/@remix-run/node
+[remix-run-cloudflare-pages]: https://npm.im/@remix-run/cloudflare-pages
+[remix-run-cloudflare-workers]: https://npm.im/@remix-run/cloudflare-workers
+[remix-run-deno]: https://npm.im/@remix-run/deno
+[remix-run-node]: https://npm.im/@remix-run/node