chore(docs): Include import case to MDX setup (#19286)

* Include import case to MDX setup I had issues with import things to MDX. I've included information about how gatsby update MDX imports and how to import them dynamically, without re-running development environment. Please merge. People had issues with this. Here for example https://spectrum.chat/mdx/general/importing-components-to-programmatically-generated-gatsby-mdx~cb7fa570-90c5-4237-b1fe-8a6d797ce030 * Make Prettier * Improve grammar Co-Authored-By: LB <barth.laurie@gmail.com> * Refactor MDXProvider with shortcodes * Include Link component to shortcodes section * Add a note to Imports section about environment restart * Apply suggestions from code review Co-Authored-By: Lennart <lekoarts@gmail.com> Co-authored-by: LB <laurie@gatsbyjs.com> Co-authored-by: Sidhartha Chatterjee <me@sidharthachatterjee.com> Co-authored-by: Lennart <lekoarts@gmail.com> Co-authored-by: GatsbyJS Bot <mathews.kyle+gatsbybot@gmail.com>
gatsbyjs · Feb 11, 2020 · 47d8453 · 47d8453
1 parent 821e83e
commit 47d8453
Show file tree

Hide file tree

Showing 2 changed files with 35 additions and 17 deletions.
diff --git a/docs/docs/mdx/programmatically-creating-pages.md b/docs/docs/mdx/programmatically-creating-pages.md
@@ -224,19 +224,27 @@ will be rendered as the template for all posts. There's a component,
 `MDXRenderer` which is used by `gatsby-plugin-mdx` that will be used to render any
 programmatically accessed MDX content.
 
+For now, to update imports within .mdx files, you should rerun your Gatsby development environment. Otherwise, it will raise a `ReferenceError`. To import things dynamically, you can use the `MDXProvider` component and provide it all the common components you'll be using, such as `Link`.
+
 First, create a component that accepts the queried MDX data (which will be
 added in the next step).
 
 ```jsx:title=src/components/posts-page-layout.js
 import React from "react"
 import { graphql } from "gatsby"
+import { MDXProvider } from "@mdx-js/react"
 import { MDXRenderer } from "gatsby-plugin-mdx"
+import { Link } from "gatsby"
+
+const shortcodes = { Link } // Provide common components here
 
 export default function PageTemplate({ data: { mdx } }) {
   return (
     <div>
       <h1>{mdx.frontmatter.title}</h1>
-      <MDXRenderer>{mdx.body}</MDXRenderer>
+      <MDXProvider components={shortcodes}>
+        <MDXRenderer>{mdx.body}</MDXRenderer>
+      </MDXProvider>
     </div>
   )
 }

diff --git a/packages/gatsby-plugin-mdx/README.md b/packages/gatsby-plugin-mdx/README.md
@@ -24,20 +24,27 @@ MDX seeks to make writing with Markdown and JSX simpler while being more express
 
 ## Table of contents
 
-- [Installation](#installation)
-- [Usage](#usage)
-  - [Configuration](#configuration)
-    - [Extensions](#extensions)
-    - [Default layouts](#default-layouts)
-    - [Imports](#imports)
-    - [Shortcodes](#shortcodes)
-    - [Gatsby remark plugins](#gatsby-remark-plugins)
-    - [Markdown plugins](#remark-plugins)
-    - [HAST plugins](#rehype-plugins)
-    - [Media types](#media-types)
-  - [Components](#components)
-    - [MDXProvider](#mdxprovider)
-    - [MDXRenderer](#mdxrenderer)
+- [What’s MDX?](#whats-mdx)
+  - [Why MDX?](#why-mdx)
+    - [Read more about MDX](#read-more-about-mdx)
+  - [Table of contents](#table-of-contents)
+  - [Installation](#installation)
+  - [Usage](#usage)
+    - [Configuration](#configuration)
+      - [Extensions](#extensions)
+      - [Default layouts](#default-layouts)
+      - [Imports](#imports)
+      - [Shortcodes](#shortcodes)
+      - [Gatsby remark plugins](#gatsby-remark-plugins)
+      - [MD plugins](#md-plugins)
+      - [HAST plugins](#hast-plugins)
+      - [Media types](#media-types)
+        - [Explanation](#explanation)
+    - [Components](#components)
+      - [MDXProvider](#mdxprovider)
+        - [Related](#related)
+      - [MDXRenderer](#mdxrenderer)
+  - [License](#license)
 
 ## Installation
 
@@ -271,6 +278,8 @@ Here's a color picker!
 <SketchPicker />
 ```
 
+_**Note:** You should rerun your Gatsby development environment to update imports in MDX files. Otherwise, you'll get a `ReferenceError` for new imports. You can use the shortcodes approach if that is an issue for you._
+
 #### Shortcodes
 
 If you want to allow usage of a component from anywhere (often referred to as a
@@ -281,16 +290,17 @@ shortcode), you can pass it to the
 // src/components/layout.js
 import React from "react"
 import { MDXProvider } from "@mdx-js/react"
+import { Link } from "gatsby"
 import { YouTube, Twitter, TomatoBox } from "./ui"
 
-const shortcodes = { YouTube, Twitter, TomatoBox }
+const shortcodes = { Link, YouTube, Twitter, TomatoBox }
 
 export default ({ children }) => (
   <MDXProvider components={shortcodes}>{children}</MDXProvider>
 )
 ```
 
-Then, in any MDX file, you can render `YouTube`, `Twitter`, and `TomatoBox` without
+Then, in any MDX file, you can navigate using `Link` and render `YouTube`, `Twitter`, and `TomatoBox` components without
 an import.
 
 ```mdx