Skip to content

Commit 97b9d59

Browse files
wooormwooorm
authoredFeb 9, 2023
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.
·
3.1.02.3.0
1 parent ea7fd0b commit 97b9d59

15 files changed

+138
-95
lines changed
 

‎docs/community/sponsor.server.mdx

+1-1
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ export const info = {
44
{name: 'Titus Wormer', github: 'wooorm', twitter: 'wooorm'}
55
],
66
published: new Date('2021-10-06'),
7-
modified: new Date('2022-01-25')
7+
modified: new Date('2022-02-01')
88
}
99

1010
# Sponsor

‎docs/community/support.server.mdx

+1-1
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ export const info = {
55
{name: 'Titus Wormer', github: 'wooorm', twitter: 'wooorm'}
66
],
77
published: new Date('2019-07-03'),
8-
modified: new Date('2022-01-25')
8+
modified: new Date('2022-02-01')
99
}
1010

1111
# Support

‎docs/docs/extending-mdx.server.mdx

+1-1
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ export const info = {
55
{name: 'Titus Wormer', github: 'wooorm', twitter: 'wooorm'}
66
],
77
published: new Date('2021-10-06'),
8-
modified: new Date('2023-01-18')
8+
modified: new Date('2023-01-19')
99
}
1010

1111
# Extending MDX

‎docs/docs/getting-started.server.mdx

+33-30
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ export const info = {
55
{name: 'Titus Wormer', github: 'wooorm', twitter: 'wooorm'}
66
],
77
published: new Date('2021-10-05'),
8-
modified: new Date('2022-06-17')
8+
modified: new Date('2022-12-14')
99
}
1010

1111
# Getting started
@@ -193,7 +193,7 @@ You can also import several types about the API of MDX files from `@types/mdx`.
193193
For example:
194194

195195
```js path="example.ts"
196-
import type {MDXComponents} from 'mdx/types'
196+
import type {MDXComponents} from 'mdx/types.js'
197197
```
198198

199199
### Security
@@ -514,33 +514,42 @@ Which in turn lets us choose whether to use the `@mdx-js/mdx` or
514514

515515
#### Astro
516516

517-
[Astro](https://astro.build/) has an [official MDX integration](https://docs.astro.build/guides/integrations-guide/mdx/).
517+
[Astro](https://astro.build/) has their own MDX integration.
518518
You can add the integration with the Astro CLI (recommended):
519519

520520
```sh
521521
npx astro add mdx
522522
```
523523

524-
This base setup allows you to import markdown, Astro components,
525-
and other MDX files as components. To use
526-
other UI framework components in your MDX files
527-
(e.g. Preact, Vue, Svelte and more),
528-
see Astro’s [Framework components](https://docs.astro.build/en/core-concepts/framework-components/) guide.
524+
This base setup allows you to import markdown, Astro components, and other MDX
525+
files as components.
526+
To use components from frameworks in your MDX files, see Astro’s
527+
[Framework components](https://docs.astro.build/core-concepts/framework-components/)
528+
guide.
529529

530-
To learn how to configure layouts, YAML frontmatter, and set up Astro’s
531-
syntax highlighting, [see their MDX
530+
For more on how to combine Astro and MDX, see [their MDX
532531
integration docs](https://docs.astro.build/guides/integrations-guide/mdx/).
533532

534533
#### Create React App (CRA)
535534

536535
<Note type="info">
537-
**Note**: rewiring with CRACO (see below) is currently required for CRA 5,
538-
due to a bug in `react-scripts`
536+
**Note**: it’s currently probably not a good idea to use CRA.
537+
</Note>
538+
539+
<Note type="info">
540+
**Note**: rewiring with CRACO is currently required for CRA 5, due to a bug
541+
in `react-scripts`
539542
([`facebook/create-react-app#12166`](https://github.com/facebook/create-react-app/issues/12166)),
540543
which is also tracked at
541544
[`mdx-js/mdx#1870`](https://github.com/mdx-js/mdx/discussions/1870).
542545
</Note>
543546

547+
<Note type="info">
548+
**Note**: warnings about CRACO having
549+
`incorrect peer dependency "react-scripts@^4.0.0"`
550+
can currently be ignored.
551+
</Note>
552+
544553
<details>
545554
<summary>Expand example</summary>
546555

@@ -560,11 +569,6 @@ integration docs](https://docs.astro.build/guides/integrations-guide/mdx/).
560569
```
561570
</details>
562571

563-
[CRA](https://github.com/facebook/create-react-app) supports webpack loaders
564-
through webpack loader syntax in imports.
565-
566-
Install the webpack loader [`@mdx-js/loader`][mdx-loader].
567-
568572
<details>
569573
<summary>Expand CRACO example</summary>
570574

@@ -593,16 +597,15 @@ Install the webpack loader [`@mdx-js/loader`][mdx-loader].
593597
```
594598
</details>
595599

600+
[CRA](https://github.com/facebook/create-react-app) supports webpack loaders
601+
through webpack loader syntax in imports.
602+
603+
Install the webpack loader [`@mdx-js/loader`][mdx-loader].
604+
596605
For importing MDX without the `!@mdx-js/loader!` prefix, you can add
597606
the loader to the webpack config, by rewiring `react-scripts` using
598607
[CRACO](http://github.com/gsoft-inc/craco).
599608

600-
<Note type="info">
601-
**Note**: warnings about CRACO having
602-
`incorrect peer dependency "react-scripts@^4.0.0"`
603-
can be ignored for the above to work.
604-
</Note>
605-
606609
See also [¶ Webpack][webpack], which is used in CRA, and see [¶ React][react],
607610
which you’re likely using, for more info.
608611

@@ -624,15 +627,15 @@ on how to use MDX with Gatsby.
624627
<summary>Expand example</summary>
625628

626629
```js path="next.config.js"
627-
import nextMDX from '@next/mdx'
630+
import nextMdx from '@next/mdx'
628631

629-
const withMDX = nextMDX({
632+
const withMdx = nextMdx({
630633
// By default only the .mdx extension is supported.
631634
extension: /\.mdx?$/,
632635
options: {/* providerImportSource: …, otherOptions… */}
633636
})
634637

635-
export default withMDX({
638+
export default withMdx({
636639
// Support MDX files as pages:
637640
pageExtensions: ['md', 'mdx', 'tsx', 'ts', 'jsx', 'js'],
638641
})
@@ -649,18 +652,18 @@ In order to use it, you need to configure the `providerImportSource` as
649652
well.
650653

651654
<details>
652-
<summary>Expand example</summary>
655+
<summary>Expand provider example</summary>
653656

654657
```js path="next.config.js"
655-
import nextMDX from '@next/mdx'
658+
import nextMdx from '@next/mdx'
656659

657-
const withMDX = nextMDX({
660+
const withMdx = nextMdx({
658661
// By default only the .mdx extension is supported.
659662
extension: /\.mdx?$/,
660663
options: {providerImportSource: '@mdx-js/react', /* otherOptions… */}
661664
})
662665

663-
export default withMDX({
666+
export default withMdx({
664667
// Support MDX files as pages:
665668
pageExtensions: ['md', 'mdx', 'tsx', 'ts', 'jsx', 'js'],
666669
})

‎docs/docs/troubleshooting-mdx.server.mdx

+1-1
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ export const info = {
55
{name: 'Titus Wormer', github: 'wooorm', twitter: 'wooorm'}
66
],
77
published: new Date('2021-10-18'),
8-
modified: new Date('2021-11-01')
8+
modified: new Date('2022-02-01')
99
}
1010

1111
{/* lint disable maximum-heading-length */}

‎docs/docs/using-mdx.server.mdx

+16-10
Original file line numberDiff line numberDiff line change
@@ -112,7 +112,8 @@ import React from 'react'
112112
import ReactDom from 'react-dom'
113113
import Example from './example.mdx' // Assumes an integration is used to compile MDX -> JS.
114114

115-
ReactDom.render(<Example />, document.querySelector('#root'))
115+
const root = ReactDom.createRoot(document.getElementById('root'))
116+
root.render(<Example />)
116117
```
117118

118119
The main content is exported as the default export.
@@ -290,7 +291,9 @@ precedence).
290291

291292
## MDX provider
292293

294+
You probably don’t need a provider.
293295
Passing components is typically fine.
296+
Providers often only add extra weight.
294297
Take for example this file:
295298

296299
```mdx path="post.mdx"
@@ -311,12 +314,12 @@ const components = {
311314
table: Table
312315
}
313316

314-
ReactDom.render(
315-
<Post components={components} />,
316-
document.querySelector('#root')
317-
)
317+
const root = ReactDom.createRoot(document.getElementById('root'))
318+
root.render(<Post components={components} />)
318319
```
319320

321+
That works, those components are used.
322+
320323
But when you’re nesting MDX files (importing them into each other) it can become
321324
cumbersome.
322325
Like so:
@@ -363,13 +366,13 @@ Set it up like so:
363366
table: Table
364367
}
365368

366-
ReactDom.render(
367-
- <Post components={components} />,
369+
const root = ReactDom.createRoot(document.getElementById('root'))
370+
-root.render(<Post components={components} />)
371+
+root.render(
368372
+ <MDXProvider components={components}>
369373
+ <Post />
370-
+ </MDXProvider>,
371-
document.querySelector('#root')
372-
)
374+
+ </MDXProvider>
375+
+)
373376
```
374377

375378
Now you can remove the explicit and verbose component passing:
@@ -423,6 +426,9 @@ In this example the current context components are discarded:
423426
…which results in `h2`s using `Component3` and `h3`s using `Component4`.
424427
No component is used for `h1`.
425428

429+
If you’re not nesting MDX files, or not nesting them often, don’t use
430+
providers: pass components explicitly.
431+
426432
[context]: https://reactjs.org/docs/context.html
427433

428434
[start]: /docs/getting-started/

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

+1-1
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ export const info = {
66
{name: 'Titus Wormer', github: 'wooorm', twitter: 'wooorm'}
77
],
88
published: new Date('2018-08-11'),
9-
modified: new Date('2021-11-01')
9+
modified: new Date('2023-01-06')
1010
}
1111

1212
# What is MDX?

‎docs/guides/frontmatter.server.mdx

+1-1
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ export const info = {
44
{name: 'Titus Wormer', github: 'wooorm', twitter: 'wooorm'}
55
],
66
published: new Date('2021-10-06'),
7-
modified: new Date('2022-06-17')
7+
modified: new Date('2022-12-14')
88
}
99

1010
# Frontmatter

‎docs/guides/gfm.server.mdx

+1-1
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ export const info = {
44
{name: 'Titus Wormer', github: 'wooorm', twitter: 'wooorm'}
55
],
66
published: new Date('2021-10-06'),
7-
modified: new Date('2022-06-17')
7+
modified: new Date('2022-12-14')
88
}
99

1010
# GitHub flavored markdown (GFM)

‎docs/guides/math.server.mdx

+1-1
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ export const info = {
55
{name: 'Titus Wormer', github: 'wooorm', twitter: 'wooorm'}
66
],
77
published: new Date('2021-10-06'),
8-
modified: new Date('2022-06-17')
8+
modified: new Date('2022-12-14')
99
}
1010

1111
# Math

‎docs/guides/mdx-on-demand.server.mdx

+21-5
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ export const info = {
55
{name: 'Titus Wormer', github: 'wooorm', twitter: 'wooorm'}
66
],
77
published: new Date('2021-11-13'),
8-
modified: new Date('2021-11-13')
8+
modified: new Date('2021-11-14')
99
}
1010

1111
# MDX on demand
@@ -28,15 +28,23 @@ On the server:
2828
```js path="server.js"
2929
import {compile} from '@mdx-js/mdx'
3030

31-
const code = String(await compile('# hi', {outputFormat: 'function-body' /* …otherOptions */ }))
31+
const code = String(await compile('# hi', {
32+
outputFormat: 'function-body',
33+
development: false
34+
// ^-- Generate code for production.
35+
// `false` if you use `/jsx-runtime` on client, `true` if you use
36+
// `/jsx-dev-runtime`.
37+
/* …otherOptions */
38+
}))
3239
// To do: send `code` to the client somehow.
3340
```
3441

3542
On the client:
3643

3744
```js path="client.js"
3845
import {run} from '@mdx-js/mdx'
39-
import * as runtime from 'react/jsx-runtime'
46+
import * as runtime from 'react/jsx-runtime' // Production.
47+
// import * as runtime from 'react/jsx-dev-runtime' // Development.
4048

4149
const code = '' // To do: get `code` from server somehow.
4250

@@ -64,7 +72,8 @@ Next.
6472

6573
```js path="pages/hello.js"
6674
import {useState, useEffect, Fragment} from 'react'
67-
import * as runtime from 'react/jsx-runtime'
75+
import * as runtime from 'react/jsx-runtime' // Production.
76+
// import * as runtime from 'react/jsx-dev-runtime' // Development.
6877
import {compile, run} from '@mdx-js/mdx'
6978

7079
export default function Page({code}) {
@@ -82,7 +91,14 @@ export default function Page({code}) {
8291

8392
export async function getStaticProps() {
8493
const code = String(
85-
await compile('# hi', {outputFormat: 'function-body' /* …otherOptions */})
94+
await compile('# hi', {
95+
outputFormat: 'function-body',
96+
development: false,
97+
// ^-- Generate code for production.
98+
// `false` if you use `/jsx-runtime` on client, `true` if you use
99+
// `/jsx-dev-runtime`.
100+
/* …otherOptions */
101+
})
86102
)
87103
return {props: {code}}
88104
}

‎docs/guides/syntax-highlighting.server.mdx

+1-1
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ export const info = {
55
{name: 'Titus Wormer', github: 'wooorm', twitter: 'wooorm'}
66
],
77
published: new Date('2021-10-06'),
8-
modified: new Date('2022-06-17')
8+
modified: new Date('2022-08-27')
99
}
1010

1111
# Syntax highlighting

‎docs/migrating/v1.server.mdx

+1-1
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ export const info = {
55
{name: 'John Otander', github: 'johno', twitter: '4lpine'}
66
],
77
published: new Date('2019-04-04'),
8-
modified: new Date('2021-11-01')
8+
modified: new Date('2021-10-17')
99
}
1010

1111
<Note type="legacy">

‎docs/migrating/v2.server.mdx

+1-1
Original file line numberDiff line numberDiff line change
@@ -387,7 +387,7 @@ You can update your code as follows:
387387

388388
const components = {/* … */}
389389
const value = '# hi'
390-
const {default: Content} = await evaluate(value, {...provider, ...runtime})
390+
const {default: Content} = await evaluate(value, {...provider, ...runtime, development: false})
391391

392392
export default () => (
393393
<Content components={components} />

‎packages/mdx/readme.md

+57-39
Original file line numberDiff line numberDiff line change
@@ -130,7 +130,7 @@ MDX document to parse (`string`, [`Buffer`][buffer] in UTF-8, [`vfile`][vfile],
130130
or anything that can be given to `vfile`).
131131

132132
<details>
133-
<summary>Example</summary>
133+
<summary>Expand example</summary>
134134

135135
```js
136136
import {VFile} from 'vfile'
@@ -149,7 +149,7 @@ await compile(new VFile({path: 'path/to/file.mdx', value: '🤭'}))
149149
List of [remark plugins][remark-plugins], presets, and pairs.
150150

151151
<details>
152-
<summary>Example</summary>
152+
<summary>Expand example</summary>
153153

154154
```js
155155
import remarkFrontmatter from 'remark-frontmatter' // YAML and such.
@@ -168,7 +168,7 @@ await compile(file, {remarkPlugins: [[remarkGfm, {singleTilde: false}], remarkFr
168168
List of [rehype plugins][rehype-plugins], presets, and pairs.
169169

170170
<details>
171-
<summary>Example</summary>
171+
<summary>Expand example</summary>
172172

173173
```js
174174
import rehypeKatex from 'rehype-katex' // Render math with KaTeX.
@@ -200,7 +200,7 @@ In particular, you might want to pass `clobberPrefix`, `footnoteLabel`, and
200200
`footnoteBackLabel`.
201201

202202
<details>
203-
<summary>Example</summary>
203+
<summary>Expand example</summary>
204204

205205
```js
206206
compile({value: '…'}, {remarkRehypeOptions: {clobberPrefix: 'comment-1'}})
@@ -233,7 +233,7 @@ The format cannot be detected if a file is passed without a path or extension:
233233
So pass a full vfile (with `path`) or an object with a path.
234234

235235
<details>
236-
<summary>Example</summary>
236+
<summary>Expand example</summary>
237237

238238
```js
239239
compile({value: '…'}) // Seen as MDX
@@ -256,7 +256,7 @@ because in those it affects *which* files are “registered”:
256256

257257
###### `options.outputFormat`
258258

259-
Output format to generate (`'program' | 'function-body'`, default: `'program'`).
259+
Output format to generate (`'function-body' | 'program'`, default: `'program'`).
260260
In most cases `'program'` should be used, as it results in a whole program.
261261
Internally, [`evaluate`][eval] uses `outputFormat: 'function-body'` to compile
262262
to code that can be `eval`ed with [`run`][run].
@@ -275,7 +275,7 @@ statements, but you can support them by setting
275275
[`options.useDynamicImport`][usedynamicimport].
276276

277277
<details>
278-
<summary>Example</summary>
278+
<summary>Expand example</summary>
279279

280280
A module `example.js`:
281281

@@ -322,7 +322,7 @@ JavaScript modules, whereas `import()` is available inside function bodies.
322322
When you turn `useDynamicImport` on, you should probably set [`options.baseUrl`][baseurl] too.
323323

324324
<details>
325-
<summary>Example</summary>
325+
<summary>Expand example</summary>
326326

327327
Say we have a couple modules:
328328

@@ -371,7 +371,7 @@ imports should run relative the path *b*.
371371
Another example is when evaluating code, whether in Node or a browser.
372372

373373
<details>
374-
<summary>Example</summary>
374+
<summary>Expand example</summary>
375375

376376
Say we have a module `example.js`:
377377

@@ -406,7 +406,7 @@ The default can be set to `true` in Node.js through environment variables: set
406406
`NODE_ENV=development`.
407407

408408
<details>
409-
<summary>Example</summary>
409+
<summary>Expand example</summary>
410410

411411
Say we had some MDX that references a component that can be passed or provided
412412
at runtime:
@@ -476,7 +476,7 @@ When given, the resulting file will have a `map` field set to a source map (in
476476
object form).
477477

478478
<details>
479-
<summary>Example</summary>
479+
<summary>Expand example</summary>
480480

481481
Assuming `example.mdx` from [§ Use][use] exists, then:
482482

@@ -515,7 +515,7 @@ The provider must export a `useMDXComponents`, which is called to access an
515515
object of components.
516516

517517
<details>
518-
<summary>Example</summary>
518+
<summary>Expand example</summary>
519519

520520
If `file` is the contents of `example.mdx` from [§ Use][use], then:
521521

@@ -556,7 +556,7 @@ The default is to compile JSX away so that the resulting file is immediately
556556
runnable.
557557

558558
<details>
559-
<summary>Example</summary>
559+
<summary>Expand example</summary>
560560

561561
If `file` is the contents of `example.mdx` from [§ Use][use], then:
562562

@@ -598,7 +598,7 @@ The classic runtime compiles to calls such as `h('p')`, the automatic runtime
598598
compiles to `import _jsx from '$importSource/jsx-runtime'\n_jsx('p')`.
599599

600600
<details>
601-
<summary>Example</summary>
601+
<summary>Expand example</summary>
602602

603603
If `file` is the contents of `example.mdx` from [§ Use][use], then:
604604

@@ -625,10 +625,10 @@ compile(file, {jsxRuntime: 'classic'})
625625

626626
Place to import automatic JSX runtimes from (`string?`, default: `'react'`).
627627
When in the `automatic` runtime, this is used to define an import for
628-
`_Fragment`, `_jsx`, and `_jsxs`.
628+
`Fragment`, `jsx`, `jsxs`, and `jsxDEV`.
629629

630630
<details>
631-
<summary>Example</summary>
631+
<summary>Expand example</summary>
632632

633633
If `file` is the contents of `example.mdx` from [§ Use][use], then:
634634

@@ -657,7 +657,7 @@ You should most probably define `pragmaFrag` and `pragmaImportSource` too when
657657
changing this.
658658

659659
<details>
660-
<summary>Example</summary>
660+
<summary>Expand example</summary>
661661

662662
If `file` is the contents of `example.mdx` from [§ Use][use], then:
663663

@@ -707,7 +707,7 @@ See `options.pragma` for an example.
707707
`Promise<VFile>` — Promise that resolves to the compiled JS as a [vfile][].
708708

709709
<details>
710-
<summary>Example</summary>
710+
<summary>Expand example</summary>
711711

712712
```js
713713
import remarkPresetLintConsistent from 'remark-preset-lint-consistent' // Lint rules to check for consistent markdown.
@@ -749,6 +749,8 @@ Typically, `import` (or `export … from`) do not work here.
749749
They can be compiled to dynamic `import()` by passing
750750
[`options.useDynamicImport`][usedynamicimport].
751751

752+
> ☢️ **Danger**: you likely must set `development: boolean`.
753+
752754
###### `file`
753755

754756
See [`compile`][compile].
@@ -759,25 +761,33 @@ Most options are the same as [`compile`][compile], with the following
759761
exceptions:
760762

761763
* `providerImportSource` is replaced by `useMDXComponents`
762-
* `jsx*` and `pragma*` options are replaced by `jsx`, `jsxs`, and `Fragment`
764+
* `jsx*` and `pragma*` options are replaced by `Fragment`, `jsx`, `jsxs`, and
765+
`jsxDEV`
763766
* `outputFormat` is set to `function-body`
764767

765768
###### `options.jsx`
766769

767770
###### `options.jsxs`
768771

772+
###### `options.jsxDEV`
773+
769774
###### `options.Fragment`
770775

771-
These three options are required.
776+
These options are required: `Fragment` always, when `development: true`
777+
then `jsx` and `jsxs`, when `development: false` then `jsxDEV`.
772778
They come from an automatic JSX runtime that you must import yourself.
773779

774780
<details>
775-
<summary>Example</summary>
781+
<summary>Expand example</summary>
776782

777783
```js
778784
import * as runtime from 'react/jsx-runtime'
779785

780-
const {default: Content} = await evaluate('# hi', {...runtime, ...otherOptions})
786+
const {default: Content} = await evaluate('# hi', {
787+
...runtime,
788+
...otherOptions,
789+
development: false
790+
})
781791
```
782792

783793
</details>
@@ -787,33 +797,38 @@ const {default: Content} = await evaluate('# hi', {...runtime, ...otherOptions})
787797
Needed if you want to support a provider.
788798

789799
<details>
790-
<summary>Example</summary>
800+
<summary>Expand example</summary>
791801

792802
```js
793803
import * as provider from '@mdx-js/react'
794804
import * as runtime from 'react/jsx-runtime'
795805

796-
const {default: Content} = await evaluate('# hi', {...provider, ...runtime, ...otherOptions})
806+
const {default: Content} = await evaluate('# hi', {
807+
...provider,
808+
...runtime,
809+
...otherOptions,
810+
development: false
811+
})
797812
```
798813

799814
</details>
800815

801816
###### Returns
802817

803-
`Promise<OMDXModule>` — Promise that resolves to something that looks a bit like
818+
`Promise<MDXModule>` — Promise that resolves to something that looks a bit like
804819
a module: an object with a `default` field set to the component and anything
805820
else that was exported from the MDX file available too.
806821

807822
<details>
808-
<summary>Example</summary>
823+
<summary>Expand example</summary>
809824

810825
Assuming the contents of `example.mdx` from [§ Use][use] was in `file`, then:
811826

812827
```js
813828
import * as runtime from 'react/jsx-runtime'
814829
import {evaluate} from '@mdx-js/mdx'
815830

816-
console.log(await evaluate(file, {...runtime}))
831+
console.log(await evaluate(file, {...runtime, development: false}))
817832
```
818833

819834
…yields:
@@ -856,8 +871,8 @@ Run MDX compiled as [`options.outputFormat: 'function-body'`][outputformat].
856871

857872
###### `options`
858873

859-
You can pass `jsx`, `jsxs`, and `Fragment` from an automatic JSX runtime as
860-
`options`.
874+
You can pass `Fragment`, `jsx`, `jsxs`, and `jsxDEV`, from an automatic JSX
875+
runtime as `options`.
861876
You can also pass `useMDXComponents` from a provider in options if the MDX is
862877
compiled with `options.providerImportSource: '#'` (the exact value of this
863878
compile option doesn’t matter).
@@ -868,14 +883,17 @@ All other options have to be passed to `compile` instead.
868883
`Promise<MDXModule>` — See `evaluate`
869884

870885
<details>
871-
<summary>Example</summary>
886+
<summary>Expand example</summary>
872887

873888
On the server:
874889

875890
```js
876891
import {compile} from '@mdx-js/mdx'
877892

878-
const code = String(await compile('# hi', {outputFormat: 'function-body'}))
893+
const code = String(await compile('# hi', {
894+
outputFormat: 'function-body',
895+
development: false
896+
}))
879897
// To do: send `code` to the client somehow.
880898
```
881899

@@ -934,15 +952,15 @@ what unified does: please read through the [`unifiedjs/unified`][unified] readme
934952
know about unified: [`core.js#L65`][core].
935953
The processor goes through these steps:
936954

937-
1. Parse MDX (serialized markdown with embedded JSX, ESM, and expressions)
955+
1. parse MDX (serialized markdown with embedded JSX, ESM, and expressions)
938956
to mdast (markdown syntax tree)
939-
2. Transform through remark (markdown ecosystem)
940-
3. Transform mdast to hast (HTML syntax tree)
941-
4. Transform through rehype (HTML ecosystem)
942-
5. Transform hast to esast (JS syntax tree)
943-
6. Do the work needed to get a component
944-
7. Transform through recma (JS ecosystem)
945-
8. Serialize esast as JavaScript
957+
2. transform through remark (markdown ecosystem)
958+
3. transform mdast to hast (HTML syntax tree)
959+
4. transform through rehype (HTML ecosystem)
960+
5. transform hast to esast (JS syntax tree)
961+
6. do the work needed to get a component
962+
7. transform through recma (JS ecosystem)
963+
8. serialize esast as JavaScript
946964

947965
The *input* is MDX (serialized markdown with embedded JSX, ESM, and
948966
expressions).

1 commit comments

Comments
 (1)

vercel[bot] commented on Feb 9, 2023

@vercel[bot]
vercel[bot]
on Feb 9, 2023

Successfully deployed to the following URLs:

mdx – ./

mdx-mdx.vercel.app
mdxjs.com
mdx-git-main-mdx.vercel.app
v2.mdxjs.com

Please sign in to comment.