Allow custom MDX components

.changeset/sharp-boats-knock.md

@@ -0,0 +1,5 @@
+---
+"@primer/gatsby-theme-doctocat": minor
+---
+
+You can now make custom React components globally available (no import required) to all markdown files in your site.

docs/content/components/index.mdx

@@ -2,5 +2,4 @@
 title: Components
 ---
 
-
-Doctocat exports a collection of components that can be imported in your project and used to enhance your markdown files.
+Doctocat provides a collection of React components that are globally available in all `.md` and `.mdx` files (no import required).

docs/content/usage/customization.mdx

@@ -1,12 +1,11 @@
 ---
 title: Customization
+description: Here are a few ways you can customize your Doctocat site.
 ---
 
 import {BorderBox} from '@primer/components'
 import {Contributors} from '@primer/gatsby-theme-doctocat'
 
-Here are a few ways you can customize your Doctocat site:
-
 ## Site metadata
 
 You can customize your site's metadata via the `siteMetadata` object in `gatsby-config.js`:
@@ -40,7 +39,7 @@ Side navigation for your site is generated from the content in `src/@primer/gats
       url: /example/example-2
 ```
 
-_Note: Doctocat only supports one level of nesting._
+<Note variant="warning">Doctocat only supports one level of nesting.</Note>
 
 ## Repository
 
@@ -177,3 +176,26 @@ Doctocat uses [`gatsby-plugin-manifest`](https://www.gatsbyjs.org/packages/gatsb
 - 512x512 pixels or larger.
 - Square. If it’s not, the image will be [letterboxed](<https://en.wikipedia.org/wiki/Letterboxing_(filming)>) with a transparent background.
 - JPEG, PNG, WebP, TIFF, GIF, or SVG format.
+
+## MDX components
+
+Doctocat uses [MDX](https://mdxjs.com/) to allow you to embed React components in your markdown files and provides a few React [components](/components) that are globally available in all `.md` and `.mdx` files (no import required). To add custom components to this list of globally available components, create an `mdx-components.js` file in `src/@primer/gatsby-theme-doctocat/` and export your custom components from this file:
+
+```js
+// src/@primer/gatsby-theme-doctocat/mdx-components.js
+import {SomeComponent} from 'path/to/some-component'
+
+export default {
+  SomeComponent,
+}
+```
+
+```md
+---
+title: Some markdown file
+---
+
+You can now use your component in any markdown file like so:
+
+<SomeComponent />
+```

theme/src/components/wrap-root-element.js

@@ -1,6 +1,7 @@
 import {MDXProvider} from '@mdx-js/react'
 import {Link, ThemeProvider} from '@primer/components'
 import React from 'react'
+import mdxComponents from '../mdx-components'
 import Blockquote from './blockquote'
 import Caption from './caption'
 import Code from './code'
@@ -36,13 +37,14 @@ const components = {
   ol: List.withComponent('ol'),
   dl: DescriptionList,
 
-  // Shortcodes (https://mdxjs.com/blog/shortcodes)
+  // Custom components
   Note,
   Do,
   Dont,
   DoDontContainer,
   Caption,
-  ImageContainer
+  ImageContainer,
+  ...mdxComponents
 }
 
 function wrapRootElement({element}) {

theme/src/mdx-components.js

@@ -0,0 +1,2 @@
+// Users can shadow this file to add custom components to scope of all MDX files.
+export default {}