From ce0d8b2e6e976df3c2eab73fbc2ddf7422760377 Mon Sep 17 00:00:00 2001
From: Lennart <lekoarts@gmail.com>
Date: Thu, 24 Nov 2022 09:02:37 +0100
Subject: [PATCH] chore(docs): Clarify MDX sourcing instructions (#37088)

---
 docs/docs/how-to/routing/mdx.md      | 38 ++++++++++++++++++++++++++--
 packages/gatsby-plugin-mdx/README.md |  9 ++++---
 2 files changed, 41 insertions(+), 6 deletions(-)

diff --git a/docs/docs/how-to/routing/mdx.md b/docs/docs/how-to/routing/mdx.md
index 68fef00a2c234..ca7ca5cc139bc 100644
--- a/docs/docs/how-to/routing/mdx.md
+++ b/docs/docs/how-to/routing/mdx.md
@@ -128,6 +128,42 @@ You can import your own components.
 
 > **Note:** 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.
 
+## Importing MDX files into JSX components
+
+You can also import MDX files into JSX components. For example, if you have a MDX file inside `src/content` that you want to include into a React component, you'll first need to make sure that `gatsby-plugin-mdx` can transpile that file. For this you have to point `gatsby-source-filesytem` to this folder:
+
+```js:title=gatsby-config.js
+module.exports = {
+  plugins: [
+    // Your other plugins...
+    {
+      resolve: `gatsby-source-filesystem`,
+      options: {
+        name: `content`,
+        path: `${__dirname}/src/content`,
+      },
+    },
+  ],
+}
+```
+
+Afterwards you'll be able to use the MDX file (the `.mdx` file extension in the import is necessary) like so:
+
+```jsx:title=src/components/component.jsx
+import * as React from "react"
+// highlight-next-line
+import SomeText from "../content/some-text.mdx"
+
+const Component = () => (
+  <main>
+    {/* highlight-next-line */}
+    <SomeText />
+  </main>
+)
+
+export default Component
+```
+
 ## Defining a layout
 
 You can use regular [layout components](/docs/how-to/routing/layout-components/) to apply layout to your sub pages.
@@ -187,8 +223,6 @@ For instance, let's say you have a Gatsby website, and you want to add support f
 
 ### Source MDX pages from the filesystem
 
-To let Gatsby know that you'll be working with MDX content you need to add `gatsby-plugin-mdx` to the plugins array in your `gatsby-config.js` file.
-
 You'll need to use `gatsby-source-filesystem` and tell it to source "posts" from a folder called `content/posts` located in the project's root.
 
 ```js:title=gatsby-config.js
diff --git a/packages/gatsby-plugin-mdx/README.md b/packages/gatsby-plugin-mdx/README.md
index 47e375e56be2f..0d68f9bd6ec3a 100644
--- a/packages/gatsby-plugin-mdx/README.md
+++ b/packages/gatsby-plugin-mdx/README.md
@@ -32,8 +32,7 @@ npm install gatsby-plugin-mdx gatsby-source-filesystem @mdx-js/react
 
 ## Usage
 
-After installing `gatsby-plugin-mdx` you can add it to your plugins list in your
-`gatsby-config.js`. You'll also want to configure `gatsby-source-filesystem` to point at your `src/pages` directory (even if you don't want to create MDX pages from `src/pages`).
+After installing `gatsby-plugin-mdx` you can add it to your plugins list in your `gatsby-config.js`. You'll also want to configure `gatsby-source-filesystem` to point at your `src/pages` directory.
 
 ```js:title=gatsby-config.js
 module.exports = {
@@ -50,11 +49,13 @@ module.exports = {
 }
 ```
 
-By default, this configuration will allow you to automatically create pages with `.mdx` files in `src/pages` and will process any Gatsby nodes with Markdown media types into MDX content.
+By default, this configuration will allow you to automatically create pages with `.mdx` files in `src/pages`.
+
+If you have MDX files in another location than `src/pages` you'll need to add another instance of `gatsby-source-filesystem` and configure the `path` to point at this folder. This is necessary for MDX files that you want to import into React components or for files you want to query via GraphQL.
 
 **Please Note:**
 
-- `gatsby-plugin-mdx` requires `gatsby-source-filesystem` to be present and configured to process local markdown files in order to generate the resulting Gatsby nodes.
+- `gatsby-plugin-mdx` requires `gatsby-source-filesystem` to be present and configured to process local MDX files in order to generate the resulting Gatsby nodes (`gatsby-source-filesystem` needs to discover all MDX files in order to create MDX nodes and allow the processing for each of them).
 - MDX syntax differs from Markdown as it only supports [CommonMark](https://commonmark.org/) by default. Nonstandard markdown features like [GitHub flavored markdown (GFM)](https://mdxjs.com/guides/gfm/) can be enabled with plugins (see [`mdxOptions` instructions](#mdxoptions)).
 - Certain features like HTML syntax doesn't work in MDX. Read the ["What is MDX?" guide](https://mdxjs.com/docs/what-is-mdx/#markdown) to learn more.