docs(workflows): new guide about importing and using components in MDX

docs/docs/mdx/customizing-components.md

@@ -1,5 +1,5 @@
 ---
-title: Customizing Components
+title: Customizing Markdown Components
 ---
 
 Using MDX, you can replace every HTML element that Markdown renders with a
@@ -28,6 +28,8 @@ export default function Layout({ children }) {
 }
 ```
 
+**Note**: you can also provide your own custom components to the `MDXProvider` that make them globally available while writing MDX. You can find more details about this pattern in the [Importing and Using Components in MDX guide](/docs/mdx/importing-and-using-components/#make-components-available-globally-as-shortcodes).
+
 The following components can be customized with the MDXProvider:
 
 | Tag             | Name                                                                 | Syntax                                              |

docs/docs/mdx/importing-and-using-components.md

@@ -0,0 +1,63 @@
+---
+title: Importing and Using Components in MDX
+---
+
+You can import your components from other third party libraries, like [`theme-ui`](https://theme-ui.com/components). Use cases for external libraries could be charting libraries for adding rich data visualizations, form components for adding email signups, styled portions of content like pullquotes, or call to action buttons throughout your pages. You can also import and reuse _your own_ React components and MDX documents.
+
+## Import components for use from another library
+
+Components imported from other libraries can be rendered inline with your markdown content, allowing you to include rich media like charts, interactive buttons, or styled messages. Components are imported at the top of your MDX files—in the same syntax they are imported in JavaScript files—and then added using opening and closing brackets like normal JSX elements.
+
+To include a component from another library (this example uses [the message component from `theme-ui`](https://theme-ui.com/components/message)), you need to import it at the top of your MDX file:
+
+```mdx
+---
+title: Importing Components Example
+---
+
+import { Message } from "theme-ui" // highlight-line
+
+You can import your own components.
+
+<Message>MDX gives you JSX in Markdown!</Message> // highlight-line
+```
+
+**Note**: steps for importing custom components or MDX documents from a relative location in your project are also covered in the [Writing Pages in MDX guide](/docs/mdx/writing-pages/).
+
+## Make components available globally as shortcodes
+
+To avoid having to import the same component inside of every MDX document you author, you can add components to an `MDXProvider` to make them globally available in MDX pages. This pattern is sometimes referred to as shortcodes.
+
+```js:title=src/components/layout.js
+import React from "react"
+// highlight-start
+import { MDXProvider } from "@mdx-js/react"
+import { Chart, Pullquote } from "./ui"
+import { Message } from "theme-ui"
+// highlight-end
+
+const shortcodes = { Chart, Pullquote, Message } // highlight-line
+
+export default ({ children }) => (
+  <MDXProvider components={shortcodes}>{children}</MDXProvider> // highlight-line
+)
+```
+
+All MDX components passed into the `components` prop of the `MDXProvider` will be made available to MDX files that are nested under the provider. The `MDXProvider` in this example is in a layout component that wraps all MDX pages, you can read about this pattern in [the layout section of the `gatsby-plugin-mdx` README](/packages/gatsby-plugin-mdx/#default-layouts).
+
+Now, you can include components in your MDX without importing them:
+
+```mdx
+---
+title: Importing Components Example
+---
+
+
+<Message>MDX gives you JSX in Mardown!</Message> // highlight-line
+
+If you want to include a Chart it's now available in all MDX files!
+
+<Chart /> // highlight-line
+```
+
+Because the `<Message />` and `<Chart />` components were passed into the provider, they are imported for you.

docs/docs/mdx/writing-pages.md

@@ -112,6 +112,8 @@ export default ({ children }) => (
 > **Note**: the default export concept used in this code block is explained in more detail
 > in the docs below on [defining layouts](#defining-a-layout)
 
+You can read more about using React components from other libraries in the [Importing and Using components in MDX guide](/docs/mdx/importing-and-using-components/).
+
 ## Combining frontmatter and imports
 
 If you would like to include frontmatter metadata _and_ import components, the frontmatter needs to appear at the top of the file and then imports can follow:

www/src/data/sidebars/doc-links.yaml

@@ -332,7 +332,10 @@
               link: /docs/mdx/getting-started/
             - title: Writing Pages
               link: /docs/mdx/writing-pages/
-            - title: Customizing Components
+            - title: Importing and Using Components in MDX
+              link: /docs/mdx/importing-and-using-components/
+              breadcrumbTitle: Importing and Using Components
+            - title: Customizing Markdown Components
               link: /docs/mdx/customizing-components/
             - title: Programmatically Creating Pages
               link: /docs/mdx/programmatically-creating-pages/