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

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
@@ -23,7 +23,7 @@ your site.
    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`.
@@ -40,7 +40,7 @@ can follow these steps for configuring the [gatsby-mdx](/packages/gatsby-mdx/) p
    yarn add gatsby-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
 
@@ -55,9 +55,9 @@ can follow these steps for configuring the [gatsby-mdx](/packages/gatsby-mdx/) p
 
 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

@@ -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

@@ -3,22 +3,22 @@ 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.
+written 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.
+> The `gatsby-mdx` plugin 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-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
+```markdown
 ---
 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 availalbe in `props.pageContext.frontmatter` and
+can be accessed in blocks of JSX in your MDX document:
+
+```markdown
+---
+title: "Building with Gatsby"
+author: "Jay Gatsby"
+---
+
+<h1>{props.pageContext.frontmatter.title}</h1>
+
+<span>{props.pageContext.frontmatter.author}</span>
+
+(Blog post content, components, etc.)
+```
+
+## Importing JSX components and MDX documents
 
 Similarly to what you'd do in JSX, you can import and render components
 with JSX. You can also import other MDX documents.
 
-```md
+```markdown: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,126 @@ 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 -->
+```markdown: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-mdx` will automatically add it to the GraphQL schema so you
+can use the exported data in your queries and in rendering.
 
-```mdx
+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 -->
+```markdown
 export const metadata = {
   name: "World",
   path: "/world",
-}
+};
 
-# Hello, <span>{props.metadata.name}</span>
+# Hello, <span children={metadata.name} /> 
 
-The heading above will say "Hello, World".
+The span above will read: "Hello, World".
+
+<!-- you can also use other variables or data structures -->
+export const names = ["Abdullah", "Adam", "Alice", "Aida"]
+
+<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):
+
+```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-mdx/?=mdx#default-layouts) in your `gatsby-config.js`
+through the `gatsby-mdx` plugin's options, the exported component you define
+from this file will replace the default.
 
-```md
+```markdown: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 -->
+```markdown
 import { graphql } from "gatsby"
 
 # My Awesome Page

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

@@ -215,7 +215,7 @@
         - title: Adding Components to Content 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/