Update CRA guide

.gitignore

@@ -11,7 +11,6 @@ bundle.js
 tmp
 artifacts
 .*cache
-public
 .npmrc
 .nyc_output/
 coverage/

docs/getting-started/create-react-app.mdx

@@ -1,50 +1,102 @@
 # Create React App
 
-Please note there’s a [known bug][] with
-the macro so live reloading doesn’t
-currently work.
-
-With Create React App you will need to use
-[`mdx.macro`][mdx-macro].
+First, create a new app with [CRA][] and change directory to enter it:
 
 ```sh
 npx create-react-app my-app
-yarn add mdx.macro
+cd my-app
+```
+
+Second, we need to configure some build tools.
+Install [`@mdx-js/loader`][loader] and [`babel-loader`][babel-loader] as dev
+dependencies:
+
+```sh
+yarn add @mdx-js/loader babel-loader --dev
+```
+
+Also make sure that JSX in MDX is handled by Babel by creating a `.babelrc` JSON
+file in the project root of `my-app`:
+
+```json
+{
+  "presets": ["@babel/preset-react"]
+}
 ```
 
-Then create the following `src/App.js`:
+Third, we can add our MDX content.
+Create an MDX file `Content.mdx` in the `src/` folder:
+
+```mdx
+export const Box = () => (
+  <div style={{padding: 20, backgroundColor: 'tomato'}} />
+)
+
+# Hello, world!
+
+This is **markdown** with <span style={{color: "red"}}>JSX</span>: MDX!
+
+<Box />
+```
+
+And to use that MDX content in the app, replace the contents of `App.js` in the
+`src/` folder with:
 
 ```js
-// src/App.js
-
-import React, {lazy, Component, Suspense} from 'react'
-import {importMDX} from 'mdx.macro'
-
-const Content = lazy(() => importMDX('./Content.mdx'))
-
-class App extends Component {
-  render() {
-    return (
-      <div>
-        <Suspense fallback={<div>Loading...</div>}>
-          <Content />
-        </Suspense>
-      </div>
-    )
-  }
+/* eslint-disable import/no-webpack-loader-syntax */
+import Content from '!babel-loader!@mdx-js/loader!./Content.mdx'
+
+function App() {
+  return <Content />
 }
 
 export default App
 ```
 
-And then create the following `src/Content.mdx`:
+We’re almost done!
+To start the development server, run:
 
-```md
-# Hello, world!
+```sh
+yarn start
 ```
 
-[See the full example][cra-example]
+**…but you will probably get this error**:
+
+```txt
+$ react-scripts start
+
+There might be a problem with the project dependency tree.
+It is likely not a bug in Create React App, but something you need to fix locally.
+
+The react-scripts package provided by Create React App requires a dependency:
+
+  "babel-loader": "$VERSION"
+…
+```
+
+CRA expects a certain `babel-loader` version but MDX also needs one.
+To fix the error, make sure the two `babel-loader` versions match, by running
+the following:
+
+```sh
+yarn add babel-loader@$VERSION --dev
+```
+
+(where `$VERSION` is the version number printed in the error message, such as
+`8.1.0`).
+
+Then, running `yarn start` again should do the trick! ✨
+
+If you’re still seeing errors and you’re using TypeScript, then [this
+guide][typescript] might help.
+
+Finally, see [Support][] if you’re still running into problems.
+
+[cra]: https://github.com/facebook/create-react-app
+[loader]: https://github.com/mdx-js/mdx/tree/main/packages/loader
+[babel-loader]: https://webpack.js.org/loaders/babel-loader/
+
+<!-- To do: update to point to website if that’s working -->
 
-[mdx-macro]: https://www.npmjs.com/package/mdx.macro
-[cra-example]: https://github.com/mdx-js/mdx/tree/master/examples/create-react-app
-[known bug]: https://github.com/facebook/create-react-app/issues/5580
+[typescript]: https://github.com/mdx-js/mdx/blob/main/docs/advanced/typescript.mdx
+[support]: https://mdxjs.com/support

docs/getting-started/index.mdx

@@ -411,7 +411,6 @@ playing around you can use `npm init`:
 - `npm init mdx` [`webpack`](/getting-started/webpack)
 - `npm init mdx` [`parcel`](/getting-started/parcel)
 - `npm init mdx` [`next`](/getting-started/next)
-- `npm init mdx` [`create-react-app`](/getting-started/create-react-app)
 - `npm init mdx` [`gatsby`](/getting-started/gatsby)
 - `npm init mdx` [`react-static`](/getting-started/react-static)
 

examples/create-react-app/readme.md

@@ -1,52 +1,6 @@
 # Create React App
 
-This project was bootstrapped with [Create React App](https://github.com/facebook/create-react-app).
+<!-- To do: link to website when it’s fixed. -->
 
-## Available Scripts
-
-In the project directory, you can run:
-
-### `npm start`
-
-Runs the app in the development mode.<br />
-Open [http://localhost:3000](http://localhost:3000) to view it in the browser.
-
-The page will reload if you make edits.<br />
-You will also see any lint errors in the console.
-
-### `npm test`
-
-Launches the test runner in the interactive watch mode.<br />
-See the section about [running tests](https://facebook.github.io/create-react-app/docs/running-tests) for more information.
-
-### `npm run build`
-
-Builds the app for production to the `build` folder.<br />
-It correctly bundles React in production mode and optimizes the build for the best performance.
-
-The build is minified and the filenames include the hashes.<br />
-Your app is ready to be deployed!
-
-See the section about [deployment](https://facebook.github.io/create-react-app/docs/deployment) for more information.
-
-### `npm run eject`
-
-**Note: this is a one-way operation.
-Once you `eject`, you can’t go back!**
-
-If you aren’t satisfied with the build tool and configuration choices, you can `eject` at any time.
-This command will remove the single build dependency from your project.
-
-Instead, it will copy all the configuration files and the transitive dependencies (Webpack, Babel, ESLint, etc) right into your project so you have full control over them.
-All of the commands except `eject` will still work, but they will point to the copied scripts so you can tweak them.
-At this point you’re on your own.
-
-You don’t have to ever use `eject`.
-The curated feature set is suitable for small and middle deployments, and you shouldn’t feel obligated to use this feature.
-However we understand that this tool wouldn’t be useful if you couldn’t customize it when you are ready for it.
-
-## Learn More
-
-You can learn more in the [Create React App documentation](https://facebook.github.io/create-react-app/docs/getting-started).
-
-To learn React, check out the [React documentation](https://reactjs.org/).
+[See this guide](https://github.com/mdx-js/mdx/blob/main/docs/getting-started/create-react-app.mdx)
+for how to use MDX with CRA!