Customizing Markdown Components

It’s possible to substitute each HTML element that MDX renders with a custom implementation as an alternative. This enables Gatsby developers to leverage a set of design system (collections of repeatable design patterns in code) components when rendering MDX files. For example, the following layout component substitutes certain elements, like <h1>, with React components that we’ve defined.

Table 13-2 lists all of the components that can be customized using the MDXProvider component.

// src/components/layout.js
import { MDXProvider } from "@mdx-js/react"
import * as DesignSystem from "your-design-system"

export default function Layout({ children }) {
  return (
    <MDXProvider
      components={{
        // Map HTML element tag to React component
        h1: DesignSystem.H1,
        h2: DesignSystem.H2,
        h3: DesignSystem.H3,
        // Or define component inline
        p: props => <p {...props} style={{ color: "rebeccapurple" }} />,
      }}
    >
      {children}
    </MDXProvider>
  )
}

MDX is one element of Gatsby’s ecosystem that can accelerate the development of Gatsby sites by enabling the interpolation of arbitrary components into Markdown documents. This introduces much greater flexibility for content authors working in Markdown who have a working knowledge of HTML as well. In the next section, we turn our attention to schema customization, another of Gatsby’s advanced features.

NOTE

The gatsby-plugin-mdx plugin is compatible with all of Gatsby’s Remark plugins, including gatsby-remark-images. For more information about using Remark plugins with MDX, consult the Gatsby documentation’s guide to MDX plugins.