Refactor to improve docs

 * Update dates * Update a bunch of examples * Refactor some wording * Update examples around `development` for `evaluate` Closes GH-2204. Closes GH-2254.

Author: wooorm

docs/community/sponsor.server.mdx

@@ -4,7 +4,7 @@ export const info = {
  {name: 'Titus Wormer', github: 'wooorm', twitter: 'wooorm'}
  ],
  published: new Date('2021-10-06'),
- modified: new Date('2022-01-25')
+ modified: new Date('2022-02-01')
 }
 
 # Sponsor

docs/community/support.server.mdx

@@ -5,7 +5,7 @@ export const info = {
  {name: 'Titus Wormer', github: 'wooorm', twitter: 'wooorm'}
  ],
  published: new Date('2019-07-03'),
- modified: new Date('2022-01-25')
+ modified: new Date('2022-02-01')
 }
 
 # Support

docs/docs/extending-mdx.server.mdx

@@ -5,7 +5,7 @@ export const info = {
  {name: 'Titus Wormer', github: 'wooorm', twitter: 'wooorm'}
  ],
  published: new Date('2021-10-06'),
- modified: new Date('2023-01-18')
+ modified: new Date('2023-01-19')
 }
 
 # Extending MDX

docs/docs/getting-started.server.mdx

@@ -5,7 +5,7 @@ export const info = {
  {name: 'Titus Wormer', github: 'wooorm', twitter: 'wooorm'}
  ],
  published: new Date('2021-10-05'),
- modified: new Date('2022-06-17')
+ modified: new Date('2022-12-14')
 }
 
 # Getting started
@@ -193,7 +193,7 @@ You can also import several types about the API of MDX files from `@types/mdx`.
 For example:
 
 ```js path="example.ts"
-import type {MDXComponents} from 'mdx/types'
+import type {MDXComponents} from 'mdx/types.js'
 ```
 
 ### Security
@@ -514,33 +514,42 @@ Which in turn lets us choose whether to use the `@mdx-js/mdx` or
 
 #### Astro
 
-[Astro](https://astro.build/) has an [official MDX integration](https://docs.astro.build/guides/integrations-guide/mdx/).
+[Astro](https://astro.build/) has their own MDX integration.
 You can add the integration with the Astro CLI (recommended):
 
 ```sh
 npx astro add mdx
 ```
 
-This base setup allows you to import markdown, Astro components,
-and other MDX files as components. To use
-other UI framework components in your MDX files
-(e.g. Preact, Vue, Svelte and more),
-see Astro’s [Framework components](https://docs.astro.build/en/core-concepts/framework-components/) guide.
+This base setup allows you to import markdown, Astro components, and other MDX
+files as components.
+To use components from frameworks in your MDX files, see Astro’s
+[Framework components](https://docs.astro.build/core-concepts/framework-components/)
+guide.
 
-To learn how to configure layouts, YAML frontmatter, and set up Astro’s
-syntax highlighting, [see their MDX
+For more on how to combine Astro and MDX, see [their MDX
 integration docs](https://docs.astro.build/guides/integrations-guide/mdx/).
 
 #### Create React App (CRA)
 
 <Note type="info">
- **Note**: rewiring with CRACO (see below) is currently required for CRA 5,
- due to a bug in `react-scripts`
+ **Note**: it’s currently probably not a good idea to use CRA.
+</Note>
+
+<Note type="info">
+ **Note**: rewiring with CRACO is currently required for CRA 5, due to a bug
+ in `react-scripts`
  ([`facebook/create-react-app#12166`](https://github.com/facebook/create-react-app/issues/12166)),
  which is also tracked at
  [`mdx-js/mdx#1870`](https://github.com/mdx-js/mdx/discussions/1870).
 </Note>
 
+<Note type="info">
+ **Note**: warnings about CRACO having
+ `incorrect peer dependency "react-scripts@^4.0.0"`
+ can currently be ignored.
+</Note>
+
 <details>
  <summary>Expand example</summary>
 
@@ -560,11 +569,6 @@ integration docs](https://docs.astro.build/guides/integrations-guide/mdx/).
  ```
 </details>
 
-[CRA](https://github.com/facebook/create-react-app) supports webpack loaders
-through webpack loader syntax in imports.
-
-Install the webpack loader [`@mdx-js/loader`][mdx-loader].
-
 <details>
  <summary>Expand CRACO example</summary>
 
@@ -593,16 +597,15 @@ Install the webpack loader [`@mdx-js/loader`][mdx-loader].
  ```
 </details>
 
+[CRA](https://github.com/facebook/create-react-app) supports webpack loaders
+through webpack loader syntax in imports.
+
+Install the webpack loader [`@mdx-js/loader`][mdx-loader].
+
 For importing MDX without the `!@mdx-js/loader!` prefix, you can add
 the loader to the webpack config, by rewiring `react-scripts` using
 [CRACO](http://github.com/gsoft-inc/craco).
 
-<Note type="info">
- **Note**: warnings about CRACO having
- `incorrect peer dependency "react-scripts@^4.0.0"`
- can be ignored for the above to work.
-</Note>
-
 See also [¶ Webpack][webpack], which is used in CRA, and see [¶ React][react],
 which you’re likely using, for more info.
 
@@ -624,15 +627,15 @@ on how to use MDX with Gatsby.
  <summary>Expand example</summary>
 
  ```js path="next.config.js"
- import nextMDX from '@next/mdx'
+ import nextMdx from '@next/mdx'
 
- const withMDX = nextMDX({
+ const withMdx = nextMdx({
  // By default only the .mdx extension is supported.
  extension: /\.mdx?$/,
  options: {/* providerImportSource: …, otherOptions… */}
  })
 
- export default withMDX({
+ export default withMdx({
  // Support MDX files as pages:
  pageExtensions: ['md', 'mdx', 'tsx', 'ts', 'jsx', 'js'],
  })
@@ -649,18 +652,18 @@ In order to use it, you need to configure the `providerImportSource` as
 well.
 
 <details>
- <summary>Expand example</summary>
+ <summary>Expand provider example</summary>
 
  ```js path="next.config.js"
- import nextMDX from '@next/mdx'
+ import nextMdx from '@next/mdx'
 
- const withMDX = nextMDX({
+ const withMdx = nextMdx({
  // By default only the .mdx extension is supported.
  extension: /\.mdx?$/,
  options: {providerImportSource: '@mdx-js/react', /* otherOptions… */}
  })
 
- export default withMDX({
+ export default withMdx({
  // Support MDX files as pages:
  pageExtensions: ['md', 'mdx', 'tsx', 'ts', 'jsx', 'js'],
  })

docs/docs/troubleshooting-mdx.server.mdx

@@ -5,7 +5,7 @@ export const info = {
  {name: 'Titus Wormer', github: 'wooorm', twitter: 'wooorm'}
  ],
  published: new Date('2021-10-18'),
- modified: new Date('2021-11-01')
+ modified: new Date('2022-02-01')
 }
 
 {/* lint disable maximum-heading-length */}

docs/docs/using-mdx.server.mdx

@@ -112,7 +112,8 @@ import React from 'react'
 import ReactDom from 'react-dom'
 import Example from './example.mdx' // Assumes an integration is used to compile MDX -> JS.
 
-ReactDom.render(<Example />, document.querySelector('#root'))
+const root = ReactDom.createRoot(document.getElementById('root'))
+root.render(<Example />)
 ```
 
 The main content is exported as the default export.
@@ -290,7 +291,9 @@ precedence).
 
 ## MDX provider
 
+You probably don’t need a provider.
 Passing components is typically fine.
+Providers often only add extra weight.
 Take for example this file:
 
 ```mdx path="post.mdx"
@@ -311,12 +314,12 @@ const components = {
  table: Table
 }
 
-ReactDom.render(
- <Post components={components} />,
- document.querySelector('#root')
-)
+const root = ReactDom.createRoot(document.getElementById('root'))
+root.render(<Post components={components} />)
 ```
 
+That works, those components are used.
+
 But when you’re nesting MDX files (importing them into each other) it can become
 cumbersome.
 Like so:
@@ -363,13 +366,13 @@ Set it up like so:
  table: Table
  }
 
- ReactDom.render(
-- <Post components={components} />,
+ const root = ReactDom.createRoot(document.getElementById('root'))
+-root.render(<Post components={components} />)
++root.render(
 + <MDXProvider components={components}>
 + <Post />
-+ </MDXProvider>,
- document.querySelector('#root')
- )
++ </MDXProvider>
++)
 ```
 
 Now you can remove the explicit and verbose component passing:
@@ -423,6 +426,9 @@ In this example the current context components are discarded:
 …which results in `h2`s using `Component3` and `h3`s using `Component4`.
 No component is used for `h1`.
 
+If you’re not nesting MDX files, or not nesting them often, don’t use
+providers: pass components explicitly.
+
 [context]: https://reactjs.org/docs/context.html
 
 [start]: /docs/getting-started/

docs/docs/what-is-mdx.server.mdx

@@ -6,7 +6,7 @@ export const info = {
  {name: 'Titus Wormer', github: 'wooorm', twitter: 'wooorm'}
  ],
  published: new Date('2018-08-11'),
- modified: new Date('2021-11-01')
+ modified: new Date('2023-01-06')
 }
 
 # What is MDX?

docs/guides/frontmatter.server.mdx

@@ -4,7 +4,7 @@ export const info = {
  {name: 'Titus Wormer', github: 'wooorm', twitter: 'wooorm'}
  ],
  published: new Date('2021-10-06'),
- modified: new Date('2022-06-17')
+ modified: new Date('2022-12-14')
 }
 
 # Frontmatter

docs/guides/gfm.server.mdx

@@ -4,7 +4,7 @@ export const info = {
  {name: 'Titus Wormer', github: 'wooorm', twitter: 'wooorm'}
  ],
  published: new Date('2021-10-06'),
- modified: new Date('2022-06-17')
+ modified: new Date('2022-12-14')
 }
 
 # GitHub flavored markdown (GFM)

docs/guides/math.server.mdx

@@ -5,7 +5,7 @@ export const info = {
  {name: 'Titus Wormer', github: 'wooorm', twitter: 'wooorm'}
  ],
  published: new Date('2021-10-06'),
- modified: new Date('2022-06-17')
+ modified: new Date('2022-12-14')
 }
 
 # Math