From 899e772866a90f8343f8696c26240bd87ec97c65 Mon Sep 17 00:00:00 2001 From: Kyle Gill Date: Fri, 7 Feb 2020 16:31:21 -0700 Subject: [PATCH 1/7] update libraries to crosslink and include data about using other components --- docs/docs/mdx/customizing-components.md | 4 +- .../mdx/importing-and-using-components.md | 64 ++++++++++++++++ docs/docs/mdx/writing-pages.md | 2 + docs/features/gatsby-features-specs.csv | 4 +- www/src/components/code-block/index.js | 1 + .../features/simple-evaluation-table.js | 76 ++++++++++--------- www/src/data/sidebars/doc-links.yaml | 5 +- 7 files changed, 117 insertions(+), 39 deletions(-) create mode 100644 docs/docs/mdx/importing-and-using-components.md diff --git a/docs/docs/mdx/customizing-components.md b/docs/docs/mdx/customizing-components.md index 3f11fc1d891c2..842d91b27b8da 100644 --- a/docs/docs/mdx/customizing-components.md +++ b/docs/docs/mdx/customizing-components.md @@ -1,5 +1,5 @@ --- -title: Customizing Components +title: Customizing Markdown Components --- Using MDX, you can replace every HTML element that Markdown renders with a @@ -28,6 +28,8 @@ export default function Layout({ children }) { } ``` +**Note**: you can also provide your own custom components to the `MDXProvider` that make them globally available while writing MDX. You can find more details about this pattern in the [Importing and Using Components in MDX guide](/docs/mdx/importing-and-using-components/#make-components-available-globally-as-shortcodes). + The following components can be customized with the MDXProvider: | Tag | Name | Syntax | diff --git a/docs/docs/mdx/importing-and-using-components.md b/docs/docs/mdx/importing-and-using-components.md new file mode 100644 index 0000000000000..d92beb4e35d3b --- /dev/null +++ b/docs/docs/mdx/importing-and-using-components.md @@ -0,0 +1,64 @@ +--- +title: Importing and Using Components in MDX +--- + +You can import your components from other third party libraries that come with components included, like [`theme-ui`](https://theme-ui.com/components). Use cases for external libraries could be charting libraries for adding rich data visualizations, form components for adding email signups, styled portions of content like pullquotes, or buttons for calls to action throughout the content in your pages. You can also import and resuse _your own_ React components and MDX documents. + +## Import components for use from another library + +Components imported from other libraries can be rendered inline with your markdown content, allowing you to include rich media like charts, interactive buttons, or styled messages. Components are imported at the top of your MDX files—in the same syntax they are imported in JavaScript files—and then added using opening and closing brackets like normal JSX elements. + +To include a component from another library (this example uses [the message component from `theme-ui`](https://theme-ui.com/components/message)), you need import it at the top of your MDX file: + +```mdx +--- +title: Importing Components Guide +--- + +import { Message } from "theme-ui" // highlight-line + +You can import your own components. + +MDX gives you JSX in Mardown! // highlight-line +``` + +**Note**: steps for importing custom components or MDX documents from a relative location in your project are also covered in the [Writing Pages in MDX guide](/docs/mdx/writing-pages/). + +## Make components available globally as shortcodes + +To avoid having to import the same component inside of every MDX document you author, you can add components to an `MDXProvider` to make them globally available in MDX pages. This pattern is sometimes referred to as shortcodes. + +```js:title=src/components/layout.js +import React from "react" +// highlight-start +import { MDXProvider } from "@mdx-js/react" +import { Chart, Pullquote } from "./ui" +import { Message } from "theme-ui" +// highlight-end + +const shortcodes = { Chart, Pullquote, Message } // highlight-line + +export default ({ children }) => ( + {children} // highlight-line +) +``` + +All MDX components passed into the `components` prop of the `MDXProvider` will be made available to MDX files that are nested under the provider. The `MDXProvider` in this example is in a layout component that would be used to wrap all MDX pages, you can read about this pattern in [the layout section of the `gatsby-plugin-mdx` README](/packages/gatsby-plugin-mdx/#default-layouts). + +Now, you can include components in your MDX without importing them: + +```mdx +--- +title: Importing Components +--- + +You can import your own components. The message component + +MDX gives you JSX in Mardown! // highlight-line + +If you want to include a Chart it's now available in all MDX files! + + // highlight-line +``` + +Because the `` and `` components were passed into the provider, they are imported for you. diff --git a/docs/docs/mdx/writing-pages.md b/docs/docs/mdx/writing-pages.md index 9c3bfe748b039..8a54159c30e23 100644 --- a/docs/docs/mdx/writing-pages.md +++ b/docs/docs/mdx/writing-pages.md @@ -112,6 +112,8 @@ export default ({ 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) +You can read more about using React components from other libraries in the [Importing and Using components in MDX guide](/docs/mdx/importing-and-using-components/). + ## Combining frontmatter and imports 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: diff --git a/docs/features/gatsby-features-specs.csv b/docs/features/gatsby-features-specs.csv index a1334219916e4..f3dd9d494ae58 100644 --- a/docs/features/gatsby-features-specs.csv +++ b/docs/features/gatsby-features-specs.csv @@ -1,6 +1,6 @@ Category,Gatsby,Jamstack,Cms,Description -Performance,3,3,2, -Developer Experience,3,3,2, +Performance,3,3,2,asdf +Developer Experience,3,3,2,asdff asdf asdf Governance,3,2,3, Accessibility,2,2,3, Documentation,3,3,3, diff --git a/www/src/components/code-block/index.js b/www/src/components/code-block/index.js index adf81a5c513cd..26f4252b82c2d 100644 --- a/www/src/components/code-block/index.js +++ b/www/src/components/code-block/index.js @@ -41,6 +41,7 @@ const CodeBlock = ({ : children, className ) + console.log({ content }) return ( diff --git a/www/src/components/features/simple-evaluation-table.js b/www/src/components/features/simple-evaluation-table.js index 652ab08f8b1c0..0b3bb42ac2c94 100644 --- a/www/src/components/features/simple-evaluation-table.js +++ b/www/src/components/features/simple-evaluation-table.js @@ -1,44 +1,50 @@ /** @jsx jsx */ import { jsx } from "theme-ui" -import React from "react" +import React, { useState } from "react" import SectionTitle from "./evaluation-table-section-title" import SectionHeaderTop from "./evaluation-table-section-header-top" import { renderCell } from "./evaluation-cell" +import { mediaQueries } from "../../gatsby-plugin-theme-ui" -const SimpleEvaluationTable = ({ title, headers, data }) => ( - - {title && } - - - h.display)} /> - {data.map(({ node }, idx) => ( - - {headers.map((header, i) => ( - - ))} - - ))} - -
`1px solid ${t.colors.ui.border}`, - minWidth: 40, - px: 0, - textAlign: `left`, - verticalAlign: `middle`, - fontSize: 1, - lineHeight: `solid`, - }} - > - {renderCell(node[header.nodeFieldProperty], i)} -
- -) +const SimpleEvaluationTable = ({ title, headers, data }) => { + const [openedDetails, setOpenedDetails] = useState() + return ( + + {title && } + + + h.display)} /> + {data.map(({ node }, idx) => ( + + + {headers.map((header, i) => ( + + ))} + + + ))} + +
`1px solid ${t.colors.ui.border}`, + minWidth: 40, + px: 0, + textAlign: `left`, + verticalAlign: `middle`, + fontSize: 1, + lineHeight: `solid`, + }} + > + {renderCell(node[header.nodeFieldProperty], i)} +
+ + ) +} export default SimpleEvaluationTable diff --git a/www/src/data/sidebars/doc-links.yaml b/www/src/data/sidebars/doc-links.yaml index a437dd6ab1606..bad80f2ccd024 100644 --- a/www/src/data/sidebars/doc-links.yaml +++ b/www/src/data/sidebars/doc-links.yaml @@ -332,7 +332,10 @@ link: /docs/mdx/getting-started/ - title: Writing Pages link: /docs/mdx/writing-pages/ - - title: Customizing Components + - title: Importing and Using Components in MDX + link: /docs/mdx/importing-and-using-components/ + breadcrumbTitle: Importing and Using Components + - title: Customizing Markdown Components link: /docs/mdx/customizing-components/ - title: Programmatically Creating Pages link: /docs/mdx/programmatically-creating-pages/ From b74cf0c8442233655fae2f27743808892084e790 Mon Sep 17 00:00:00 2001 From: Kyle Gill Date: Fri, 7 Feb 2020 16:43:04 -0700 Subject: [PATCH 2/7] revisions to remove wrongly committed code --- .../mdx/importing-and-using-components.md | 6 +- docs/features/gatsby-features-specs.csv | 4 +- www/src/components/code-block/index.js | 1 - .../features/simple-evaluation-table.js | 76 +++++++++---------- 4 files changed, 40 insertions(+), 47 deletions(-) diff --git a/docs/docs/mdx/importing-and-using-components.md b/docs/docs/mdx/importing-and-using-components.md index d92beb4e35d3b..81523e401c4d1 100644 --- a/docs/docs/mdx/importing-and-using-components.md +++ b/docs/docs/mdx/importing-and-using-components.md @@ -12,7 +12,7 @@ To include a component from another library (this example uses [the message comp ```mdx --- -title: Importing Components Guide +title: Importing Components Example --- import { Message } from "theme-ui" // highlight-line @@ -49,10 +49,10 @@ Now, you can include components in your MDX without importing them: ```mdx --- -title: Importing Components +title: Importing Components Example --- -You can import your own components. The message component +You can import your own components. MDX gives you JSX in Mardown! // highlight-line diff --git a/docs/features/gatsby-features-specs.csv b/docs/features/gatsby-features-specs.csv index f3dd9d494ae58..a1334219916e4 100644 --- a/docs/features/gatsby-features-specs.csv +++ b/docs/features/gatsby-features-specs.csv @@ -1,6 +1,6 @@ Category,Gatsby,Jamstack,Cms,Description -Performance,3,3,2,asdf -Developer Experience,3,3,2,asdff asdf asdf +Performance,3,3,2, +Developer Experience,3,3,2, Governance,3,2,3, Accessibility,2,2,3, Documentation,3,3,3, diff --git a/www/src/components/code-block/index.js b/www/src/components/code-block/index.js index 26f4252b82c2d..adf81a5c513cd 100644 --- a/www/src/components/code-block/index.js +++ b/www/src/components/code-block/index.js @@ -41,7 +41,6 @@ const CodeBlock = ({ : children, className ) - console.log({ content }) return ( diff --git a/www/src/components/features/simple-evaluation-table.js b/www/src/components/features/simple-evaluation-table.js index 0b3bb42ac2c94..652ab08f8b1c0 100644 --- a/www/src/components/features/simple-evaluation-table.js +++ b/www/src/components/features/simple-evaluation-table.js @@ -1,50 +1,44 @@ /** @jsx jsx */ import { jsx } from "theme-ui" -import React, { useState } from "react" +import React from "react" import SectionTitle from "./evaluation-table-section-title" import SectionHeaderTop from "./evaluation-table-section-header-top" import { renderCell } from "./evaluation-cell" -import { mediaQueries } from "../../gatsby-plugin-theme-ui" -const SimpleEvaluationTable = ({ title, headers, data }) => { - const [openedDetails, setOpenedDetails] = useState() - return ( - - {title && } - - - h.display)} /> - {data.map(({ node }, idx) => ( - - - {headers.map((header, i) => ( - - ))} - - - ))} - -
`1px solid ${t.colors.ui.border}`, - minWidth: 40, - px: 0, - textAlign: `left`, - verticalAlign: `middle`, - fontSize: 1, - lineHeight: `solid`, - }} - > - {renderCell(node[header.nodeFieldProperty], i)} -
- - ) -} +const SimpleEvaluationTable = ({ title, headers, data }) => ( + + {title && } + + + h.display)} /> + {data.map(({ node }, idx) => ( + + {headers.map((header, i) => ( + + ))} + + ))} + +
`1px solid ${t.colors.ui.border}`, + minWidth: 40, + px: 0, + textAlign: `left`, + verticalAlign: `middle`, + fontSize: 1, + lineHeight: `solid`, + }} + > + {renderCell(node[header.nodeFieldProperty], i)} +
+ +) export default SimpleEvaluationTable From 0d741521dcfbec5c89b7d6c6103f3324df653221 Mon Sep 17 00:00:00 2001 From: Kyle Gill Date: Wed, 12 Feb 2020 08:43:25 -0700 Subject: [PATCH 3/7] Apply suggestions from code review Co-Authored-By: LB --- docs/docs/mdx/importing-and-using-components.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/docs/docs/mdx/importing-and-using-components.md b/docs/docs/mdx/importing-and-using-components.md index 81523e401c4d1..f5b8cf390eb5b 100644 --- a/docs/docs/mdx/importing-and-using-components.md +++ b/docs/docs/mdx/importing-and-using-components.md @@ -2,13 +2,13 @@ title: Importing and Using Components in MDX --- -You can import your components from other third party libraries that come with components included, like [`theme-ui`](https://theme-ui.com/components). Use cases for external libraries could be charting libraries for adding rich data visualizations, form components for adding email signups, styled portions of content like pullquotes, or buttons for calls to action throughout the content in your pages. You can also import and resuse _your own_ React components and MDX documents. +You can import your components from other third party libraries, like [`theme-ui`](https://theme-ui.com/components). Use cases for external libraries could be charting libraries for adding rich data visualizations, form components for adding email signups, styled portions of content like pullquotes, or call to action buttons throughout your pages. You can also import and reuse _your own_ React components and MDX documents. ## Import components for use from another library Components imported from other libraries can be rendered inline with your markdown content, allowing you to include rich media like charts, interactive buttons, or styled messages. Components are imported at the top of your MDX files—in the same syntax they are imported in JavaScript files—and then added using opening and closing brackets like normal JSX elements. -To include a component from another library (this example uses [the message component from `theme-ui`](https://theme-ui.com/components/message)), you need import it at the top of your MDX file: +To include a component from another library (this example uses [the message component from `theme-ui`](https://theme-ui.com/components/message)), you need to import it at the top of your MDX file: ```mdx --- @@ -19,7 +19,7 @@ import { Message } from "theme-ui" // highlight-line You can import your own components. -MDX gives you JSX in Mardown! // highlight-line +MDX gives you JSX in Markdown! // highlight-line ``` **Note**: steps for importing custom components or MDX documents from a relative location in your project are also covered in the [Writing Pages in MDX guide](/docs/mdx/writing-pages/). @@ -43,7 +43,7 @@ export default ({ children }) => ( ) ``` -All MDX components passed into the `components` prop of the `MDXProvider` will be made available to MDX files that are nested under the provider. The `MDXProvider` in this example is in a layout component that would be used to wrap all MDX pages, you can read about this pattern in [the layout section of the `gatsby-plugin-mdx` README](/packages/gatsby-plugin-mdx/#default-layouts). +All MDX components passed into the `components` prop of the `MDXProvider` will be made available to MDX files that are nested under the provider. The `MDXProvider` in this example is in a layout component that wraps all MDX pages, you can read about this pattern in [the layout section of the `gatsby-plugin-mdx` README](/packages/gatsby-plugin-mdx/#default-layouts). Now, you can include components in your MDX without importing them: @@ -52,7 +52,6 @@ Now, you can include components in your MDX without importing them: title: Importing Components Example --- -You can import your own components. MDX gives you JSX in Mardown! // highlight-line From e863ee6beadbc290af1b83307202e06003d2be0a Mon Sep 17 00:00:00 2001 From: Kyle Gill Date: Wed, 12 Feb 2020 08:43:54 -0700 Subject: [PATCH 4/7] Update docs/docs/mdx/importing-and-using-components.md --- docs/docs/mdx/importing-and-using-components.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/mdx/importing-and-using-components.md b/docs/docs/mdx/importing-and-using-components.md index f5b8cf390eb5b..2962df0d5cea5 100644 --- a/docs/docs/mdx/importing-and-using-components.md +++ b/docs/docs/mdx/importing-and-using-components.md @@ -53,7 +53,7 @@ title: Importing Components Example --- -MDX gives you JSX in Mardown! // highlight-line +MDX gives you JSX in Markdown! // highlight-line If you want to include a Chart it's now available in all MDX files! From 4fe671cadad66b40cfd90dd8554c5ac746627d06 Mon Sep 17 00:00:00 2001 From: Kyle Gill Date: Wed, 12 Feb 2020 09:02:30 -0700 Subject: [PATCH 5/7] update example to clarify shortcode example --- docs/docs/mdx/importing-and-using-components.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/docs/mdx/importing-and-using-components.md b/docs/docs/mdx/importing-and-using-components.md index 2962df0d5cea5..b8e243991430d 100644 --- a/docs/docs/mdx/importing-and-using-components.md +++ b/docs/docs/mdx/importing-and-using-components.md @@ -43,21 +43,22 @@ export default ({ children }) => ( ) ``` -All MDX components passed into the `components` prop of the `MDXProvider` will be made available to MDX files that are nested under the provider. The `MDXProvider` in this example is in a layout component that wraps all MDX pages, you can read about this pattern in [the layout section of the `gatsby-plugin-mdx` README](/packages/gatsby-plugin-mdx/#default-layouts). +All MDX components passed into the `components` prop of the `MDXProvider` will be made available to MDX documents that are nested under the provider. The `MDXProvider` in this example is in a layout component that wraps all MDX pages, you can read about this pattern in [the layout section of the `gatsby-plugin-mdx` README](/packages/gatsby-plugin-mdx/#default-layouts). Now, you can include components in your MDX without importing them: ```mdx --- -title: Importing Components Example +title: Shortcode Components Example --- +Now, if you want to include the Message component, it's available in all MDX documents! MDX gives you JSX in Markdown! // highlight-line -If you want to include a Chart it's now available in all MDX files! +The Chart is also available since it was passed into the MDXProvider: // highlight-line ``` -Because the `` and `` components were passed into the provider, they are imported for you. +Because the `` and `` components were passed into the provider, they are imported for you at the top of all MDX documents. From 9c7ea0fa0cee4e657ec00913a086ca0790d574b1 Mon Sep 17 00:00:00 2001 From: Kyle Gill Date: Wed, 12 Feb 2020 09:04:10 -0700 Subject: [PATCH 6/7] one more change from mdx files to mdx documents --- docs/docs/mdx/importing-and-using-components.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/mdx/importing-and-using-components.md b/docs/docs/mdx/importing-and-using-components.md index b8e243991430d..1f40368cd4b24 100644 --- a/docs/docs/mdx/importing-and-using-components.md +++ b/docs/docs/mdx/importing-and-using-components.md @@ -6,7 +6,7 @@ You can import your components from other third party libraries, like [`theme-ui ## Import components for use from another library -Components imported from other libraries can be rendered inline with your markdown content, allowing you to include rich media like charts, interactive buttons, or styled messages. Components are imported at the top of your MDX files—in the same syntax they are imported in JavaScript files—and then added using opening and closing brackets like normal JSX elements. +Components imported from other libraries can be rendered inline with your markdown content, allowing you to include rich media like charts, interactive buttons, or styled messages. Components are imported at the top of your MDX documents—in the same syntax they are imported in JavaScript files—and then added using opening and closing brackets like normal JSX elements. To include a component from another library (this example uses [the message component from `theme-ui`](https://theme-ui.com/components/message)), you need to import it at the top of your MDX file: From a0da672de5c8f8e8b4590a194fc84a9c85797a90 Mon Sep 17 00:00:00 2001 From: Kyle Gill Date: Tue, 18 Feb 2020 09:41:00 -0700 Subject: [PATCH 7/7] Update docs/docs/mdx/importing-and-using-components.md Co-Authored-By: LB --- docs/docs/mdx/importing-and-using-components.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/mdx/importing-and-using-components.md b/docs/docs/mdx/importing-and-using-components.md index 1f40368cd4b24..aa39db9c3a895 100644 --- a/docs/docs/mdx/importing-and-using-components.md +++ b/docs/docs/mdx/importing-and-using-components.md @@ -61,4 +61,4 @@ The Chart is also available since it was passed into the MDXProvider: // highlight-line ``` -Because the `` and `` components were passed into the provider, they are imported for you at the top of all MDX documents. +Because the `` and `` components were passed into the provider, they are available for use in all MDX documents.