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.
mdx-js · Feb 9, 2023 · 97b9d59 · 97b9d59 · vercel · Feb 9, 2023
1 parent ea7fd0b
commit 97b9d59
Show file tree

Hide file tree

Showing 15 changed files with 138 additions and 95 deletions.
diff --git a/docs/community/sponsor.server.mdx b/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

diff --git a/docs/community/support.server.mdx b/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

diff --git a/docs/docs/extending-mdx.server.mdx b/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

diff --git a/docs/docs/getting-started.server.mdx b/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'],
   })

diff --git a/docs/docs/troubleshooting-mdx.server.mdx b/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 */}

diff --git a/docs/docs/using-mdx.server.mdx b/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/

diff --git a/docs/docs/what-is-mdx.server.mdx b/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?

diff --git a/docs/guides/frontmatter.server.mdx b/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

diff --git a/docs/guides/gfm.server.mdx b/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)

diff --git a/docs/guides/math.server.mdx b/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

diff --git a/docs/guides/mdx-on-demand.server.mdx b/docs/guides/mdx-on-demand.server.mdx
@@ -5,7 +5,7 @@ export const info = {
     {name: 'Titus Wormer', github: 'wooorm', twitter: 'wooorm'}
   ],
   published: new Date('2021-11-13'),
-  modified: new Date('2021-11-13')
+  modified: new Date('2021-11-14')
 }
 
 # MDX on demand
@@ -28,15 +28,23 @@ On the server:
 ```js path="server.js"
 import {compile} from '@mdx-js/mdx'
 
-const code = String(await compile('# hi', {outputFormat: 'function-body' /* …otherOptions */ }))
+const code = String(await compile('# hi', {
+  outputFormat: 'function-body',
+  development: false
+  // ^-- Generate code for production.
+  // `false` if you use `/jsx-runtime` on client, `true` if you use
+  // `/jsx-dev-runtime`.
+  /* …otherOptions */
+}))
 // To do: send `code` to the client somehow.
 ```
 
 On the client:
 
 ```js path="client.js"
 import {run} from '@mdx-js/mdx'
-import * as runtime from 'react/jsx-runtime'
+import * as runtime from 'react/jsx-runtime' // Production.
+// import * as runtime from 'react/jsx-dev-runtime' // Development.
 
 const code = '' // To do: get `code` from server somehow.
 
@@ -64,7 +72,8 @@ Next.
 
 ```js path="pages/hello.js"
 import {useState, useEffect, Fragment} from 'react'
-import * as runtime from 'react/jsx-runtime'
+import * as runtime from 'react/jsx-runtime' // Production.
+// import * as runtime from 'react/jsx-dev-runtime' // Development.
 import {compile, run} from '@mdx-js/mdx'
 
 export default function Page({code}) {
@@ -82,7 +91,14 @@ export default function Page({code}) {
 
 export async function getStaticProps() {
   const code = String(
-    await compile('# hi', {outputFormat: 'function-body' /* …otherOptions */})
+    await compile('# hi', {
+      outputFormat: 'function-body',
+      development: false,
+      // ^-- Generate code for production.
+      // `false` if you use `/jsx-runtime` on client, `true` if you use
+      // `/jsx-dev-runtime`.
+      /* …otherOptions */
+    })
   )
   return {props: {code}}
 }

diff --git a/docs/guides/syntax-highlighting.server.mdx b/docs/guides/syntax-highlighting.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-08-27')
 }
 
 # Syntax highlighting

diff --git a/docs/migrating/v1.server.mdx b/docs/migrating/v1.server.mdx
@@ -5,7 +5,7 @@ export const info = {
     {name: 'John Otander', github: 'johno', twitter: '4lpine'}
   ],
   published: new Date('2019-04-04'),
-  modified: new Date('2021-11-01')
+  modified: new Date('2021-10-17')
 }
 
 <Note type="legacy">

diff --git a/docs/migrating/v2.server.mdx b/docs/migrating/v2.server.mdx
@@ -387,7 +387,7 @@ You can update your code as follows:
 
     const components = {/* … */}
     const value = '# hi'
-    const {default: Content} = await evaluate(value, {...provider, ...runtime})
+    const {default: Content} = await evaluate(value, {...provider, ...runtime, development: false})
 
     export default () => (
       <Content components={components} />