docs: restore original README to allow dedicated review

gatsbyjs · Jun 27, 2022 · 9657416 · 9657416
1 parent 19758de
commit 9657416
Showing 1 changed file with 105 additions and 11 deletions.
diff --git a/packages/gatsby-plugin-mdx/README.md b/packages/gatsby-plugin-mdx/README.md
@@ -38,19 +38,21 @@ MDX seeks to make writing with Markdown and JSX simpler while being more express
       - [Gatsby remark plugins](#gatsby-remark-plugins)
       - [Remark plugins](#remark-plugins)
       - [Rehype plugins](#rehype-plugins)
+      - [Media types](#media-types)
+        - [Explanation](#explanation)
+      - [shouldBlockNodeFromTransformation](#shouldblocknodefromtransformation)
     - [Components](#components)
       - [MDXProvider](#mdxprovider)
         - [Related](#related)
-  - [Troubleshooting](#troubleshooting)
-    - [Excerpts for non-latin languages](#excerpts-for-non-latin-languages)
+      - [MDXRenderer](#mdxrenderer)
   - [License](#license)
 
 ## Installation
 
 Install:
 
 ```shell
-npm install gatsby-plugin-mdx @mdx-js/react
+npm install gatsby-plugin-mdx @mdx-js/mdx@v1 @mdx-js/react@v1
 ```
 
 ## Usage
@@ -111,13 +113,16 @@ module.exports = {
 any other Gatsby plugin. You can define MDX extensions, layouts, global
 scope, and more.
 
-| Key                                             | Default    | Description                                                       |
-| ----------------------------------------------- | ---------- | ----------------------------------------------------------------- |
-| [`extensions`](#extensions)                     | `[".mdx"]` | Configure the file extensions that gatsby-plugin-mdx will process |
-| [`defaultLayouts`](#default-layouts)            | `{}`       | Set the layout components for MDX source types                    |
-| [`gatsbyRemarkPlugins`](#gatsby-remark-plugins) | `[]`       | Use Gatsby-specific remark plugins                                |
-| [`remarkPlugins`](#remark-plugins)              | `[]`       | Specify remark plugins                                            |
-| [`rehypePlugins`](#rehype-plugins)              | `[]`       | Specify rehype plugins                                            |
+| Key                                                                       | Default                                | Description                                                           |
+| ------------------------------------------------------------------------- | -------------------------------------- | --------------------------------------------------------------------- |
+| [`extensions`](#extensions)                                               | `[".mdx"]`                             | Configure the file extensions that gatsby-plugin-mdx will process     |
+| [`defaultLayouts`](#default-layouts)                                      | `{}`                                   | Set the layout components for MDX source types                        |
+| [`gatsbyRemarkPlugins`](#gatsby-remark-plugins)                           | `[]`                                   | Use Gatsby-specific remark plugins                                    |
+| [`remarkPlugins`](#remark-plugins)                                        | `[]`                                   | Specify remark plugins                                                |
+| [`rehypePlugins`](#rehype-plugins)                                        | `[]`                                   | Specify rehype plugins                                                |
+| [`mediaTypes`](#media-types)                                              | `["text/markdown", "text/x-markdown"]` | Determine which media types are processed by MDX                      |
+| [`shouldBlockNodeFromTransformation`](#shouldblocknodefromtransformation) | `(node) => false`                      | Disable MDX transformation for nodes where this function returns true |
+| [`commonmark`](#commonmark)                                               | `false`                                | Use CommonMark                                                        |
 
 #### Extensions
 
@@ -406,6 +411,61 @@ module.exports = {
 }
 ```
 
+#### Media types
+
+Deciding what content gets processed by `gatsby-plugin-mdx`. This is an
+advanced option that is useful for dealing with specialized generated
+content. It is not intended to be configured for most users.
+
+```js
+// gatsby-config.js
+module.exports = {
+  plugins: [
+    {
+      resolve: `gatsby-plugin-mdx`,
+      options: {
+        mediaTypes: [`text/markdown`, `text/x-markdown`],
+      },
+    },
+  ],
+}
+```
+
+##### Explanation
+
+Gatsby includes the media-type of the content on any given node. For
+`file` nodes, we choose whether to process the content with MDX or not
+by the file extension. For remote content or generated content, we
+choose which nodes to process by looking at the media type.
+
+#### shouldBlockNodeFromTransformation
+
+Given a function `(node) => Boolean` allows you to decide for each node if it should be transformed or not.
+
+```js
+// gatsby-config.js
+module.exports = {
+  plugins: [
+    {
+      resolve: `gatsby-plugin-mdx`,
+      options: {
+        shouldBlockNodeFromTransformation(node) {
+          return (
+            [`NPMPackage`, `NPMPackageReadme`].includes(node.internal.type) ||
+            (node.internal.type === `File` &&
+              path.parse(node.dir).dir.endsWith(`packages`))
+          )
+        },
+      },
+    },
+  ],
+}
+```
+
+#### CommonMark
+
+MDX will be parsed using CommonMark.
+
 ### Components
 
 MDX and `gatsby-plugin-mdx` use components for different things like rendering
@@ -481,7 +541,41 @@ You can also expose any custom component to every mdx file using
 
 ##### Related
 
-- [React context for MDX](https://mdxjs.com/packages/react/#use)
+- [MDX components](https://mdxjs.com/getting-started/#mdxprovider)
+
+#### MDXRenderer
+
+`MDXRenderer` is a React component that takes _compiled_ MDX content and
+renders it. You will need to use this if your MDX content is coming
+from a GraphQL page query or `StaticQuery`.
+
+`MDXRenderer` takes any prop and passes it on to your MDX content,
+just like a normal React component.
+
+```jsx
+<MDXRenderer title="My Stuff!">{mdx.body}</MDXRenderer>
+```
+
+Using a page query:
+
+```jsx
+import { MDXRenderer } from "gatsby-plugin-mdx"
+
+export default class MyPageLayout {
+  render() {
+    return <MDXRenderer>{this.props.data.mdx.body}</MDXRenderer>
+  }
+}
+
+export const pageQuery = graphql`
+  query MDXQuery($id: String!) {
+    mdx(id: { eq: $id }) {
+      id
+      body
+    }
+  }
+`
+```
 
 ## Troubleshooting