docs(www): 25 Workflows - Embedding components in Markdown with MDX (#14543)

* chore: updates to docs to improve examples and provide more detailed explanations

* fix: simple grammatcial changes

* fix: PR review suggestions

* fix: correct code block titles and update example inline jsx

* Amberleys PR comments

* feat: add mdx as a title to code blocks

* add link to glossary for components to help disambiguate

* Update docs/docs/mdx/index.md

Co-Authored-By: Marcy Sutton <[email protected]>

* Update docs/docs/mdx/index.md

Co-Authored-By: Marcy Sutton <[email protected]>

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

Co-Authored-By: Marcy Sutton <[email protected]>

* local merge conflicts + github suggestions = confusion

Author: gillkyle

docs/docs/adding-markdown-pages.md

@@ -71,9 +71,9 @@ plugins: [
 Create a folder in the `/src` directory of your Gatsby application called `markdown-pages`.
 Now create a Markdown file inside it with the name `post-1.md`.
 
-#### Including frontmatter
+#### Frontmatter for metadata in markdown files
 
-When you create a Markdown file, at the top of the file, add the frontmatter (metadata) block below. You can have different key value pairs that are relevant to your website. This block will be parsed by `gatsby-transformer-remark` as `frontmatter`. The GraphQL API will provide this data in your React components.
+When you create a Markdown file, you can include a set of key value pairs that can be used to provide additional data relevant to specific pages in the GraphQL data layer. This data is called frontmatter and is denoted by the triple dashes at the start and end of the block. This block will be parsed by `gatsby-transformer-remark` as `frontmatter`. The GraphQL API will provide the key value pairs as data in our React components.
 
 ```markdown:title=src/markdown-pages/post-1.md
 ---

docs/docs/mdx/getting-started.md

@@ -1,5 +1,5 @@
 ---
-title: Getting Started
+title: Getting Started with MDX
 ---
 
 The fastest way to get started with Gatsby + MDX is to use the [MDX
@@ -19,11 +19,10 @@ your site.
 
    ```sh
    cd my-mdx-starter/
-   npm install
    gatsby develop
    ```
 
-1. **Open the site** running at http://localhost:8000!
+1. **Open the site** running at http://localhost:8000
 
 1. **Update the MDX content** by opening the `my-mdx-starter` directory
    in your code editor of choice and edit `src/pages/index.mdx`.
@@ -37,27 +36,27 @@ can follow these steps for configuring the [gatsby-mdx](/packages/gatsby-mdx/) p
 1. **Add `gatsby-mdx`** and MDX as dependencies
 
    ```sh
-   yarn add gatsby-mdx @mdx-js/mdx @mdx-js/react
+   yarn add gatsby-plugin-mdx @mdx-js/mdx @mdx-js/react
    ```
 
-   If you're upgrading from v0, [check out the MDX migration guide](https://mdxjs.com/migrating/v1).
+   > **Note:** If you're upgrading from v0, additionally [check out the MDX migration guide](https://mdxjs.com/migrating/v1).
 
-1. **Update your `gatsby-config.js`** to use the `gatsby-mdx` plugin
+1. **Update your `gatsby-config.js`** to use `gatsby-plugin-mdx`
 
    ```javascript:title=gatsby-config.js
    module.exports = {
      plugins: [
        // ....
-       `gatsby-mdx`,
+       `gatsby-plugin-mdx`,
      ],
    }
    ```
 
 1. **Restart `gatsby develop`** and add an `.mdx` page to `src/pages
 
-**Note:** If you want to query for frontmatter, exports, or other fields like
-`tableOfContents` and you haven't previously added a `gatsby-source-filesystem`
-pointing at `src/pages` in your project, you'll want to add one now.
+> **Note:** If you want to query for frontmatter, exports, or other fields like
+> `tableOfContents` and you haven't previously added a `gatsby-source-filesystem`
+> pointing at `src/pages` in your project, you'll want to add one now.
 
 ## What's next?
 

docs/docs/mdx/index.md

@@ -1,8 +1,8 @@
 ---
-title: Adding Components to Content with MDX
+title: Adding Components to Markdown with MDX
 ---
 
-When writing long-form content in Markdown you might want to embed components.
+When writing long-form content in Markdown you might want to embed [components](/docs/glossary/#component).
 This is often achieved by either writing content in JSX or using plugins that
 use custom syntax. The first approach isn't optimal because JSX isn't the best
 format for content and can make it less approachable to members of a team. Custom
@@ -15,8 +15,8 @@ you're finding yourself wanting to add components to your content you can use
 [MDX][mdx] is Markdown for the component era.
 It lets you write JSX embedded inside Markdown.
 It’s a great combination because it allows you to use Markdown’s terse
-syntax (such as `# Heading`) for your content and JSX for more advanced
-components.
+syntax (such as `# Heading`) for your content and JSX for more advanced,
+or reusable components.
 
 This is useful in content-driven sites where you want the ability
 to introduce components like charts or alerts without having to
@@ -27,14 +27,13 @@ interactions.
 
 When using MDX you can also import other MDX documents and render
 them as components. This lets you write something like an FAQ
-page in one place and render it throughout your website.
+page in one place and reuse it throughout your website.
 
 ## What does it look like in practice?
 
-MDX might seem weird at first, but it quickly feels natural
-after working with it for a few minutes. Importing and JSX
-syntax works just like in your components. This results in a
-seamless experience for developers and content authors alike.
+Importing and JSX syntax works just like it does in your components. This
+results in a seamless experience for developers and content authors alike.
+Markdown and JSX are included alongside each other like this:
 
 ```md
 import { Chart } from '../components/chart'

docs/docs/mdx/programmatically-creating-pages.md

@@ -32,7 +32,7 @@ root.
 
 > **NOTE**: `gatsby-mdx` uses `.mdx` by default as a file extension to
 > recognize which files to use. You can also [use `.md` as a file
-> extension](api-reference/options/extensions) if you want.
+> extension](https://gatsby-mdx.netlify.com/api-reference/options/extensions) if you want.
 
 ```javascript=gatsby-config.js
 module.exports = {
@@ -54,7 +54,7 @@ module.exports = {
 ```
 
 You can read about
-[`gatsby-source-filesystem`](https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-source-filesystem#readme)
+[`gatsby-source-filesystem`](/packages/gatsby-source-filesystem)
 if you'd like to learn more.
 
 ## Add MDX Files

docs/docs/mdx/writing-pages.md

@@ -2,23 +2,23 @@
 title: Writing Pages in MDX
 ---
 
-After [installing](/docs/mdx/getting-started) the plugin, MDX files
-written in `src/pages` will turn into pages. This happens because
-`gatsby-mdx` looks for MDX files and automatically transpiles them
-so that Gatsby internals can render them.
+After [installing](/docs/mdx/getting-started) `gatsby-plugin-mdx`, MDX files
+located in `src/pages` will turn into pages.
 
 Pages are rendered at a URL that is constructed from the filesystem
 path inside `src/pages`. An MDX file at `src/pages/awesome.mdx` will
 result in a page being rendered at `mysite.com/awesome`.
 
-By default, gatsby-mdx supports frontmatter so you can define things
-like titles and paths to use in your GraphQL queries.
+> `gatsby-plugin-mdx` looks for MDX files and automatically
+> transpiles them so that Gatsby internals can render them.
 
-## Frontmatter
+## Using frontmatter in MDX
 
-You can declare frontmatter at the beginning of your MDX document:
+By default, `gatsby-plugin-mdx` supports [frontmatter](/docs/adding-markdown-pages/#frontmatter-for-metadata-in-markdown-files)
+so you can define things like titles and paths to use in your GraphQL
+queries. You can declare frontmatter at the beginning of your MDX document:
 
-```md
+```mdx
 ---
 title: Hello, world!
 path: /hello-world
@@ -30,17 +30,14 @@ date: 2019-01-29
 
 Which can then be [queried with GraphQL](/docs/querying-with-graphql/):
 
-**Note:** To query `Mdx` content, it must be included in the node system using a
-source like `gatsby-source-filesystem` first.
-
 ```graphql
 query {
   allMdx {
     edges {
       node {
         frontmatter {
-          path
           title
+          path
           date(formatString: "MMMM DD, YYYY")
         }
       }
@@ -49,14 +46,34 @@ query {
 }
 ```
 
-## Importing components
+> **Note:** To query `Mdx` content, it must be included in the node system using a
+> source like the `gatsby-source-filesystem` plugin first. Instructions for sourcing
+> content from somewhere like your `/src/pages` directory can be found on the [plugin's README](/packages/gatsby-source-filesystem/).
+
+Frontmatter is also available in `props.pageContext.frontmatter` and
+can be accessed in blocks of JSX in your MDX document:
+
+```mdx
+---
+title: "Building with Gatsby"
+author: "Jay Gatsby"
+---
+
+<h1>{props.pageContext.frontmatter.title}</h1>
+
+<span>{props.pageContext.frontmatter.author}</span>
+
+(Blog post content, components, etc.)
+```
 
-Similarly to what you'd do in JSX, you can import and render components
-with JSX. You can also import other MDX documents.
+## Importing JSX components and MDX documents
 
-```md
+Similarly to what you'd do in plain React, you can import and render JSX components
+directly in MDX files. You can also import other MDX documents.
+
+```mdx:title=src/pages/chart.mdx
 import { Chart } from "../components/chart"
-import FAQ from "../content/faq.mdx"
+import FAQ from "../components/faq.mdx"
 
 # Here’s a chart
 
@@ -67,47 +84,127 @@ The chart is rendered inside our MDX document.
 <FAQ />
 ```
 
-## Exports
+The `<Chart />` component coming from a `.js` file would be written like any
+other React component, while the `<FAQ />` component coming from an `.mdx`
+file might look something like this:
+
+<!-- prettier-ignore -->
+```mdx:title=src/components/faq.mdx
+## Frequently Asked Questions
+
+### Why Gatsby?
+
+Gatsby delivers faster, more secure sites and apps from a variety of data 
+sources
+
+### Where do I start?
+
+The documentation offers guides for all different skill levels, you can 
+find more info at the Gatsby's [Quick Start page](https://www.gatsbyjs.org/docs/quick-start)
+
+<!-- This default export overrides the default layout ensuring -->
+<!--  that the FAQ component isn't wrapped by other elements -->
+export default ({ children }) => (
+  <>
+    {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)
+
+## Using JavaScript exports
+
+MDX supports `export` syntax as well, which enables specific use cases like providing data
+for queries and rendering or overriding the default layout on MDX documents. You
+don't need to export MDX documents to import them in other files.
+
+### Exporting page metadata
 
-MDX supports `export` syntax as well which allows you to export metadata
-about a given document. gatsby-mdx will automatically add it to the
-GraphQL schema so you can use the exported data in your queries and
-rendering.
+You can provide additional data about a given document by exporting.
+`gatsby-plugin-mdx` will automatically add it to the GraphQL schema so you
+can use the exported data in your queries and in rendering.
 
+Data exported in MDX documents in this manner is also made available on the
+variable name you've assigned it.
+
+You can export variables, objects, or other data structures:
+
+<!-- prettier-ignore -->
 ```mdx
 export const metadata = {
   name: "World",
   path: "/world",
-}
+};
+
+# Hello, <span children={metadata.name} /> 
+
+The span above will read: "Hello, World".
+
+<!-- you can also use other variables or data structures -->
+export const names = ["Abdullah", "Adam", "Alice", "Aida"]
 
-# Hello, <span>{props.metadata.name}</span>
+<ul>{names.map(name => <li>{name}</li>)}</ul>
+```
+
+The fields `name` and `path` defined on `metadata` could now alternatively
+be accessed on MDX nodes in other areas of your Gatsby project by a GraphQL
+query like this (this query fetches all MDX nodes and the data exports
+associated with them):
 
-The heading above will say "Hello, World".
+```graphql
+query MdxExports {
+  allMdx {
+    nodes {
+      exports {
+        metadata {
+          name
+          path
+        }
+      }
+    }
+  }
+}
 ```
 
 ### Defining a layout
 
-You can specify the layout that will wrap your component using the
-default export.
+If you have [provided a default layout](/packages/gatsby-plugin-mdx/?=mdx#default-layouts) in your `gatsby-config.js`
+through the `gatsby-plugin-mdx` plugin options, the exported component you define
+from this file will replace the default.
 
-```md
+<!-- prettier-ignore -->
+```mdx:title=src/pages/layout-example.mdx
 import PurpleBorder from "../components/purple-border"
 
 # This will have a purple border
 
 export default PurpleBorder
 ```
 
+The `<PurpleBorder />` component might look something like this, wrapping the MDX
+document in a `<div>` with a 1px purple border:
+
+```jsx:title=src/components/purple-border.js
+import React from "react"
+
+const PurpleBorder = ({ children }) => (
+  <div style={{ border: "1px solid rebeccapurple" }}>{children}</div>
+)
+
+export default PurpleBorder
+```
+
 ## GraphQL Queries
 
 You can fetch data to use in your MDX file by exporting a `pageQuery`
 in the same way you would for a `.js` page. The queried data is passed
 as a prop, and can be accessed inside any JSX block when writing in
 MDX:
 
-<!-- This is invalid JSX; prettier has a bug with this code snippet -->
-
-```jsx
+<!-- prettier-ignore -->
+```mdx
 import { graphql } from "gatsby"
 
 # My Awesome Page

docs/tutorial/writing-documentation-with-docz.md

@@ -44,7 +44,7 @@ module.exports = {
 
 Docz searches your directories for `mdx` files and renders them. Create a `docs` folder at the root of your project. Place an `index.mdx` file inside this directory with the following content:
 
-```md:title=docs/index.mdx
+```mdx:title=docs/index.mdx
 ---
 name: Getting Started
 route: /
@@ -102,7 +102,7 @@ The button will display its text by default with a `font-size` of `18px` however
 
 Create a new file in the `docs` directory to document your newly created button component. Call the file `button.mdx`:
 
-```md:title=docs/button.mdx
+```mdx:title=docs/button.mdx
 ---
 name: Button
 menu: Components
@@ -115,7 +115,7 @@ Buttons make common actions more obvious and help users more easily perform them
 
 Docz offers some internal components you can use to display the component and its properties. Import both these and your component itself into the document and use them:
 
-```md:title=docs/button.mdx
+```mdx:title=docs/button.mdx
 ---
 name: Button
 menu: Components

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

@@ -218,10 +218,10 @@
                   link: /docs/tailwind-css/
                 - title: Using Bulma
                   link: /docs/bulma/
-        - title: Adding Components to Content with MDX
+        - title: Adding Components to Markdown with MDX
           link: /docs/mdx/
           items:
-            - title: Getting Started
+            - title: Getting Started with MDX
               link: /docs/mdx/getting-started/
             - title: Writing Pages
               link: /docs/mdx/writing-pages/