Markdown

Setup

Upgrades

v2.x - breaking upgrade

overview

Gatsby recently (4.21) announced support for mdx2. I really didn't see a lot wrong with the way v1 was running, but the new version promises to scale and build much better, has extensive configuration options (like adding github markdown extensions), and is maintained. Gatsby still doesn't fully support ESM, so there is quite a bit of the remark/markdown ecosystem that is kludgy at the moment, but there are some interesting packages on the horizon.

official example plugin doc options future rehype plugins future remark plugins

• remove @mdx-js/mdx 1.6.22
• @mdx-js/react 1.6.22 goes to 2.1.2
• gatsby-plugin-mdx 3.20.0 goes to 4.0.0
• breaking changes to configs and every page

npm changes

• npm uninstall @mdx-js/mdx
• npm i @mdx-js/react@2 gatsby-plugin-mdx@4

gatsby-config

• remove any gatsby-remark-images mention outside of gatsbyRemarkPlugins
• change options for gatsby-plugin-mdx
• no longer allows for specification of defaultLayouts
• other options link

my gatsby-config

    {
      resolve: "gatsby-plugin-mdx",
      options: {
        gatsbyRemarkPlugins: [
          {
            resolve: "gatsby-remark-images",
            options: {
              maxWidth: 1200,
            },
          }
        ],
      }
    },

layout hack

mdx has a special component: the layout. If defined, it is used to wrap all content. This simulates the mdx v1 behaviour of wrapping the content in the gatsby-config

add layout in the header of every mdx file

• export {Layout as default} from './components.js' or if Layout is the default component use
• import Layout from '../../components/layout';
• export default Layout

OR wrap layout in config

added to gatsby-browser and gatsby-ssr

export const wrapPageElement = ({ element,props }) => {
  return (
    <SnackbarProvider maxSnack={3} dense preventDuplicate>
      <Layout {...props}>
        {element}
      </Layout>
    </SnackbarProvider>
)};

new gatsby-node

runs to generate mdx pages with custom layout wrappers, not necessary in our simple case

gatsby-browser, ssr

• requires layout to be used in the wrapPageElement we can longer have LayoutPub and Layout as separate choices for layouts.
• alternately, can require in mdx header

pages with layout components

remove the component

mdx content changes

• comments - <!-- comment --> goes to {/* */}