gatsby-transformer-mdx

Mdx files handling in Gatsby sites.

Install

As an npm package:

npm i -D gatsby-transformer-mdx

How to use

Default case

In your gatsby-config.js:

module.exports = {
  plugins: ['gatsby-transformer-mdx'],
};

This way all your mdx files in src/pages will converted to pages. Also you can import mdx files as any other React component.

Using MDX to programmatically create pages

// gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: 'gatsby-source-filesystem',
      options: {
        name: 'blog',
        path: `${__dirname}/src/content/blog`,
      },
    },
    'gatsby-transformer-mdx',
  ],
};

// gatsby-node.js
exports.createPages = async ({ actions, graphql }) => {
  const { createPage } = actions;
  const result = await graphql(`
    {
      allMdx(filter: { sourceName: { eq: "blog" } }) {
        edges {
          node {
            id
            fileAbsolutePath
            frontmatter {
              pathname
            }
          }
        }
      }
    }
  `);

  if (result.errors) throw result.errors;

  result.data.allMdx.edges.forEach(({ node }) => {
    const {
      frontmatter: { pathname },
    } = node;

    createPage({
      path: `/blog${pathname}`,
      component: node.fileAbsolutePath,
      context: { id: node.id },
    });
  });
};

Options

• pagesPath
• loaders
• defaultLayout
• defaultImports

Define mdx pages location with pagesPath

// gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: 'gatsby-transformer-mdx',
      options: {
        pagesPath: `${__dirname}/src/blog`,
      },
    },
  ],
};

* The default is __dirname + '/src/pages'.

Altering the webpack mdx loaders with loaders

// gatsby-config.js
const emoji = require('remark-emoji');

module.exports = {
  plugins: [
    {
      resolve: 'gatsby-transformer-mdx',
      options: {
        loaders: {
          // eg. Disable babel-loader cache
          js: () => ({ cacheDirectory: false }),
          // eg. Use emoji plugin
          mdx: () => ({ mdPlugins: [emoji] }),
        },
      },
    },
  ],
};

Checkout the demo.

Define default mdx layout with defaultLayout

Pass the absolute path to module:

// gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: 'gatsby-transformer-mdx',
      options: {
        defaultLayout: `${__dirname}/src/layouts/PurpleLayout`,
      },
    },
    'gatsby-plugin-catch-links',
  ],
};

You can always override it with export default syntax.

Checkout the demo.

* Make sure that the provided default layout module exports the layout component as default.

Adding components to mdx scope with defaultImports

// gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: 'gatsby-transformer-mdx',
      options: {
        defaultImports: [
          "import Clock from 'react-live-clock';",
          { value: '{ PinkBox }', path: `${__dirname}/src/ui` },
        ],
      },
    },
  ],
};

<!-- any-mdx-file.mdx -->

# The time is <Clock format="HH:mm:ss" ticking />

<PinkBox>
  Lore ipsum
</PinkBox>

Checkout the demo.

License

MIT