docs: small updates

.eslintrc.js

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

CONTRIBUTING.md

@@ -1 +1 @@
-Please see [our guide to contributing](docs/pages/contributing.md).
+Please see [our guide to contributing](docs/guides/contributing).

README.md

@@ -4,7 +4,7 @@ We are happy you're here!
 
 [Remix](https://remix.run) is a full stack web framework that lets you focus on the user interface and work back through web fundamentals to deliver a fast, slick, and resilient user experience that deploys to any Node.js server and even non-Node.js environments at the edge like Cloudflare Workers.
 
-Want to know more? Read the [Technical Explanation of Remix](https://remix.run/pages/technical-explanation)
+Want to know more? Read the [Technical Explanation of Remix](https://remix.run/discussion/introduction)
 
 This repository contains the Remix source code. This repo is a work in progress, so we appreciate your patience as we figure things out.
 
@@ -19,7 +19,7 @@ The documentation is automatically generated on each release from the files in
 
 ## Contributing
 
-If you're interested in contributing code and/or documentation, please see [our guide to contributing](docs/pages/contributing.md).
+If you're interested in contributing code and/or documentation, please see [our guide to contributing](docs/guides/contributing).
 
 ## Code of Conduct
 

docs/components/await.md

@@ -1,13 +1,12 @@
 ---
 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 { Await } from "@remix-run/react";
@@ -23,21 +22,21 @@ import { Await } from "@remix-run/react";
 
 ### `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 +48,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 +73,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 +88,7 @@ function SomeChild() {
 }
 ```
 
-[defer]: ../utils/defer
-[streaming-guide]: ../guides/streaming
-[useloaderdata]: ../hooks/use-loader-data
-[streaming-guide-2]: ../guides/streaming
-[use-async-error]: ../hooks/use-async-error
+[streaming_guide]: ../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

@@ -4,16 +4,16 @@ title: Form
 
 # `<Form>`
 
-A progressively enhanced HTML `<form>` wrapper, useful for submissions that should also change the URL or otherwise add an entry to the browser history stack. For forms that shouldn't manipulate the browser history stack, use [`<fetcher.Form>`][fetcher-form].
+A progressively enhanced HTML [`<form>`][form_element] wrapper, useful for submissions that should also change the URL or otherwise add an entry to the browser history stack. For forms that shouldn't manipulate the browser history stack, use [`<fetcher.Form>`][fetcher_form].
 
 ```tsx
 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>
   );
 }
@@ -25,17 +25,17 @@ function NewEvent() {
 
 The URL to submit the form data to.
 
-If `undefined`, the action defaults to the closest route in context. If a parent route renders a `<Form>` but the URL matches deeper child routes, the form will post to the parent route. Likewise, a form inside the child route will post to the child route. This differs from a native `<form>` that will always point to the full URL.
+If `undefined`, this defaults to the closest route in context. If a parent route renders a `<Form>` but the URL matches deeper child routes, the form will post to the parent route. Likewise, a form inside the child route will post to the child route. This differs from a native [`<form>`][form_element] that will always point to the full URL.
 
 ### `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 you should avoid the other verbs if you'd like to support [progressive enhancement][progressive-enhancement]
+Native [`<form>`][form_element] only supports `GET` and `POST`, so you should avoid the other verbs if you'd like to support [progressive enhancement][progressive_enhancement]
 
 ### `encType`
 
@@ -45,8 +45,17 @@ The encoding type to use for the form submission.
 <Form encType="multipart/form-data" />
 ```
 
+<!-- this can also be `text/plain` -->
 Defaults to `application/x-www-form-urlencoded`, use `multipart/form-data` for file uploads.
 
+### `preventScrollReset`
+
+If you are using [`<ScrollRestoration>`][scroll_restoration_component], this lets you prevent the scroll position from being reset to the top of the window when the form is submitted.
+
+```tsx
+<Form preventScrollReset />
+```
+
 ### `replace`
 
 Replaces the current entry in the history stack, instead of pushing the new entry.
@@ -63,7 +72,7 @@ If true, it will submit the form with the browser instead of client side routing
 <Form reloadDocument />
 ```
 
-This is recommended over `<form />`. When the `action` prop is omitted, `<Form>` and `<form>` will sometimes call different actions depending on what the current URL is since `<form>` uses the current URL as the default, but `<Form>` uses the URL for the route the form is rendered in.
+This is recommended over [`<form>`][form_element]. When the `action` prop is omitted, `<Form>` and `<form>` will sometimes call different actions depending on what the current URL is since `<form>` uses the current URL as the default, but `<Form>` uses the URL for the route the form is rendered in.
 
 ## Notes
 
@@ -82,39 +91,41 @@ Because index routes and their parent route share the same URL, the `?index` par
 
 See also:
 
-- [`?index` query param][index query param]
+- [`?index` query param][index_query_param]
 
 ## Additional Resources
 
 **Videos:**
 
-- [Data Mutations with Form + action][data-mutations-with-form-action]
-- [Multiple Forms and Single Button Mutations][multiple-forms-and-single-button-mutations]
-- [Clearing Inputs After Form Submissions][clearing-inputs-after-form-submissions]
+- [Data Mutations with Form + action][data_mutations_with_form_action]
+- [Multiple Forms and Single Button Mutations][multiple_forms_and_single_button_mutations]
+- [Clearing Inputs After Form Submissions][clearing_inputs_after_form_submissions]
 
 **Related Discussions:**
 
-- [Fullstack Data Flow][fullstack-data-flow]
-- [Pending UI][pending-ui]
-- [Form vs. Fetcher][form-vs-fetcher]
+- [Fullstack Data Flow][fullstack_data_flow]
+- [Pending UI][pending_ui]
+- [Form vs. Fetcher][form_vs_fetcher]
 
 **Related APIs:**
 
-- [`useNavigation`][usenavigation]
-- [`useActionData`][useactiondata]
-- [`useSubmit`][usesubmit]
-
-[index query param]: ../guides/routing#what-is-the-index-query-param
-[usenavigation]: ../hooks/use-navigation
-[useactiondata]: ../hooks/use-action-data
-[usesubmit]: ../hooks/use-submit
-[http-verb]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods
-[rr-form]: https://reactrouter.com/components/form
-[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
-[fullstack-data-flow]: ../discussion/data-flow
-[pending-ui]: ../discussion/pending-ui
-[form-vs-fetcher]: ../discussion/form-vs-fetcher
-[fetcher-form]: ../hooks/use-fetcher
-[progressive-enhancement]: ../discussion/progressive-enhancement
+- [`useActionData`][use_action_data]
+- [`useNavigation`][use_navigation]
+- [`useSubmit`][use_submit]
+
+[use_navigation]: ../hooks/use-navigation
+[scroll_restoration_component]: ./scroll-restoration
+<!-- page doesn't exist anymore -->
+[index_query_param]: ../guides/routing#what-is-the-index-query-param
+[http_verb]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods
+[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
+[fullstack_data_flow]: ../discussion/data-flow
+[pending_ui]: ../discussion/pending-ui
+[form_vs_fetcher]: ../discussion/form-vs-fetcher
+[fetcher_form]: ../hooks/use-fetcher#fetcherform
+[progressive_enhancement]: ../discussion/progressive-enhancement

docs/components/link.md

@@ -47,7 +47,7 @@ Because of this, if you are using `nav :last-child` you will need to use `nav :l
 
 ### `preventScrollReset`
 
-If you are using [`<ScrollRestoration>`][scroll-restoration], this lets you prevent the scroll position from being reset to the top of the window when the link is clicked.
+If you are using [`<ScrollRestoration>`][scroll_restoration_component], this lets you prevent the scroll position from being reset to the top of the window when the link is clicked.
 
 ```tsx
 <Link to="?tab=one" preventScrollReset />
@@ -56,11 +56,12 @@ If you are using [`<ScrollRestoration>`][scroll-restoration], this lets you prev
 This does not prevent the scroll position from being restored when the user comes back to the location with the back/forward buttons, it just prevents the reset when the user clicks the link.
 
 <details>
+
 <summary>Discussion</summary>
 
 An example when you might want this behavior is a list of tabs that manipulate the url search params that aren't at the top of the page. You wouldn't want the scroll position to jump up to the top because it might scroll the toggled content out of the viewport!
 
-```
+```text
       ┌─────────────────────────┐
       │                         ├──┐
       │                         │  │
@@ -137,15 +138,14 @@ Adds persistent client side routing state to the next location.
 
 The location state is accessed from the `location`.
 
-```ts
+```tsx
 function SomeComp() {
   const location = useLocation();
   location.state; // { some: "value" }
 }
 ```
 
-This state is inaccessible on the server as it is implemented on top of [`history.state`][history-state].
+This state is inaccessible on the server as it is implemented on top of [`history.state`][history_state].
 
-[rr-link]: https://reactrouter.com/en/main/components/link
-[scroll-restoration]: ./scroll-restoration
-[history-state]: https://developer.mozilla.org/en-US/docs/Web/API/History/state
+[scroll_restoration_component]: ./scroll-restoration
+[history_state]: https://developer.mozilla.org/en-US/docs/Web/API/History/state

docs/components/links.md

@@ -5,9 +5,9 @@ toc: false
 
 # `<Links />`
 
-The `<Links/>` component renders all of the `<link>` tags created by your route module [`links`][links] export. You should render it inside the `<head>` of your HTML, usually in `app/root.tsx`.
+The `<Links/>` component renders all of the [`<link>`][link_element] tags created by your route module [`links`][links] export. You should render it inside the [`<head>`][head_element] of your HTML, usually in `app/root.tsx`.
 
-```tsx filename=root.tsx lines=[7]
+```tsx filename=app/root.tsx lines=[7]
 import { Links } from "@remix-run/react";
 
 export default function Root() {
@@ -22,4 +22,6 @@ export default function Root() {
 }
 ```
 
+[link_element]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/link
+[head_element]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/head
 [links]: ../route/links

docs/components/live-reload.md

@@ -5,9 +5,9 @@ toc: false
 
 # `<LiveReload />`
 
-This component connects your app to the Remix asset server and automatically reloads the page when files change in development. In production it renders `null`, so you can safely render it always in your root route.
+This component connects your app to the Remix asset server and automatically reloads the page when files change in development. In production, it renders `null`, so you can safely render it always in your root route.
 
-```tsx filename=root.tsx lines=[8]
+```tsx filename=app/root.tsx lines=[8]
 import { LiveReload } from "@remix-run/react";
 
 export default function Root() {

docs/components/meta.md

@@ -5,9 +5,9 @@ toc: false
 
 # `<Meta />`
 
-This component renders all of the `<meta>` tags created by your route module [`meta`][meta] export. You should render it inside the `<head>` of your HTML, usually in `app/root.tsx`.
+This component renders all of the [`<meta>`][meta_element] tags created by your route module [`meta`][meta] export. You should render it inside the [`<head>`][head_element] of your HTML, usually in `app/root.tsx`.
 
-```tsx filename=root.tsx lines=[7]
+```tsx filename=app/root.tsx lines=[7]
 import { Meta } from "@remix-run/react";
 
 export default function Root() {
@@ -22,4 +22,6 @@ export default function Root() {
 }
 ```
 
+[meta_element]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta
+[head_element]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/head
 [meta]: ../route/meta

docs/components/nav-link.md

@@ -1,11 +1,10 @@
 ---
 title: NavLink
-toc: false
 ---
 
 # `<NavLink>`
 
-Wraps [`<Link>`][link-2] with additional props for styling active and pending states.
+Wraps [`<Link>`][link_component] with additional props for styling active and pending states.
 
 ```tsx
 import { NavLink } from "@remix-run/react";
@@ -24,7 +23,7 @@ import { NavLink } from "@remix-run/react";
 
 ### `.active`
 
-An `active` class is added to a `<NavLink>` component when it is active so you can use CSS to style it.
+An `active` class is added to a `<NavLink>` component when it is active, so you can use CSS to style it.
 
 ```tsx
 <NavLink to="/messages" />
@@ -38,7 +37,7 @@ a.active {
 
 ### `aria-current`
 
-When a `NavLink` is active it will automatically apply `<a aria-current="page">` to the underlying anchor tag. See [aria-current][aria-current] on MDN.
+When a `NavLink` is active it will automatically apply `<a aria-current="page">` to the underlying anchor tag. See [aria_current][aria_current] on MDN.
 
 ## Props
 
@@ -89,7 +88,7 @@ Calls back with the active and pending states to allow customizing the content o
 
 ### `end`
 
-The `end` prop changes the matching logic for the `active` and `pending` states to only match to the "end" of the NavLinks's `to` path. If the URL is longer than `to`, it will no longer be considered active.
+The `end` prop changes the matching logic for the `active` and `pending` states to only match to the "end" of the `NavLinks`'s `to` path. If the URL is longer than `to`, it will no longer be considered active.
 
 | Link                          | URL          | isActive |
 | ----------------------------- | ------------ | -------- |
@@ -102,7 +101,7 @@ The `end` prop changes the matching logic for the `active` and `pending` states
 
 ### `caseSensitive`
 
-Adding the `caseSensitive` prop changes the matching logic to make it case sensitive.
+Adding the `caseSensitive` prop changes the matching logic to make it case-sensitive.
 
 | Link                                         | URL           | isActive |
 | -------------------------------------------- | ------------- | -------- |
@@ -111,8 +110,7 @@ Adding the `caseSensitive` prop changes the matching logic to make it case sensi
 
 ### `<Link>` props
 
-All other props of [`<Link>`][link] are supported.
+All other props of [`<Link>`][link_component] are supported.
 
-[aria-current]: https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-current
-[link]: ./link
-[link-2]: ./link
+[link_component]: ./link
+[aria_current]: https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-current