From df94c22ac01496e32ac1e61d055b2df95ab2d98b Mon Sep 17 00:00:00 2001 From: gillkyle Date: Tue, 18 Jun 2019 22:12:31 -0600 Subject: [PATCH] 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 * Update docs/docs/mdx/index.md Co-Authored-By: Marcy Sutton * Update www/src/data/sidebars/doc-links.yaml Co-Authored-By: Marcy Sutton * local merge conflicts + github suggestions = confusion --- docs/docs/adding-markdown-pages.md | 4 +- docs/docs/mdx/getting-started.md | 19 +-- docs/docs/mdx/index.md | 17 +- .../mdx/programmatically-creating-pages.md | 4 +- docs/docs/mdx/writing-pages.md | 161 ++++++++++++++---- .../writing-documentation-with-docz.md | 6 +- www/src/data/sidebars/doc-links.yaml | 4 +- www/src/utils/typography.js | 6 + 8 files changed, 161 insertions(+), 60 deletions(-) diff --git a/docs/docs/adding-markdown-pages.md b/docs/docs/adding-markdown-pages.md index b72a6b5b5dd12..8c7593e15b9d2 100644 --- a/docs/docs/adding-markdown-pages.md +++ b/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 --- diff --git a/docs/docs/mdx/getting-started.md b/docs/docs/mdx/getting-started.md index 0d3316b19ec56..09fff2b992552 100644 --- a/docs/docs/mdx/getting-started.md +++ b/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? diff --git a/docs/docs/mdx/index.md b/docs/docs/mdx/index.md index ea901add324b2..757a6e9e47950 100644 --- a/docs/docs/mdx/index.md +++ b/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' diff --git a/docs/docs/mdx/programmatically-creating-pages.md b/docs/docs/mdx/programmatically-creating-pages.md index 5e61a51b6a5ff..1079c9a08d64f 100644 --- a/docs/docs/mdx/programmatically-creating-pages.md +++ b/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 diff --git a/docs/docs/mdx/writing-pages.md b/docs/docs/mdx/writing-pages.md index 3ae7177f14e91..31eed6d30391e 100644 --- a/docs/docs/mdx/writing-pages.md +++ b/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" +--- + +

{props.pageContext.frontmatter.title}

+ +{props.pageContext.frontmatter.author} + +(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,30 +84,98 @@ The chart is rendered inside our MDX document. ``` -## Exports +The `` component coming from a `.js` file would be written like any +other React component, while the `` component coming from an `.mdx` +file might look something like this: + + +```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) + + + +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: + + ```mdx export const metadata = { name: "World", path: "/world", -} +}; + +# Hello, + +The span above will read: "Hello, World". + + +export const names = ["Abdullah", "Adam", "Alice", "Aida"] -# Hello, {props.metadata.name} +
    {names.map(name =>
  • {name}
    • )}
+``` + +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 + +```mdx:title=src/pages/layout-example.mdx import PurpleBorder from "../components/purple-border" # This will have a purple border @@ -98,6 +183,19 @@ import PurpleBorder from "../components/purple-border" export default PurpleBorder ``` +The `` component might look something like this, wrapping the MDX +document in a `
` with a 1px purple border: + +```jsx:title=src/components/purple-border.js +import React from "react" + +const PurpleBorder = ({ children }) => ( +
{children}
+) + +export default PurpleBorder +``` + ## GraphQL Queries You can fetch data to use in your MDX file by exporting a `pageQuery` @@ -105,9 +203,8 @@ 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: - - -```jsx + +```mdx import { graphql } from "gatsby" # My Awesome Page diff --git a/docs/tutorial/writing-documentation-with-docz.md b/docs/tutorial/writing-documentation-with-docz.md index 99fd1ca9cbfe4..9c83ff1343bdb 100644 --- a/docs/tutorial/writing-documentation-with-docz.md +++ b/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 diff --git a/www/src/data/sidebars/doc-links.yaml b/www/src/data/sidebars/doc-links.yaml index 10e5e97264345..9fb87d1a635c7 100644 --- a/www/src/data/sidebars/doc-links.yaml +++ b/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/ diff --git a/www/src/utils/typography.js b/www/src/utils/typography.js index 37f1f4062e766..094af2d39f258 100644 --- a/www/src/utils/typography.js +++ b/www/src/utils/typography.js @@ -138,6 +138,12 @@ const _options = { background: `#ff9800`, color: colors.white, }, + ".gatsby-highlight pre[class='language-mdx']::before": { + content: `'mdx'`, + background: `#f9ac00`, + color: colors.white, + fontWeight: `400`, + }, ".gatsby-highlight pre[class='language-shell']::before": { content: `'shell'`, },