Working with MDX Files

This guide covers the major changes in MDX files introduced with the Gatsby upgrade from v3 to v5, essential for writing blogs and other MDX pages. Adhering to these updates is crucial to avoid unexpected outputs and potential build errors.

Changes in the MDX Syntax

• Using the updated MDX syntax is essential to prevent build errors and project failures.
• With the recent upgrade, the project now uses MDX v2. Some important changes include:
  • HTML syntax is no longer supported; only JSX syntax will work. For example, <img> needs to be updated to <img />.
  • Comments must now follow JSX formatting, using {/* */}.
  • Unescaped left angle brackets (<) and left curly braces ({) need to be escaped with \< or \{, or alternatively, use expressions like {'<'} or {'{'}. Please note that this is only for the cases where these elements are used separately. This does not include cases when we are writing JSX. For instance, writing is still the same, we don't need to write \< img/> to write JSX.
  • More details are available in the plugin migration guide.
• Additional changes can be reviewed in the MDX v2 official documentation.
• It has been observed that styling in several MDX files, particularly in blogs, was previously done using strings, such as <div style="width:16em;">. This approach should be replaced with object syntax, like <div style={{width: "16em"}}>, to avoid errors during the build process.

IntelliSense for MDX Syntax

• Using an IntelliSense extension for the latest MDX syntax is highly recommended. This extension for VS Code effectively identifies syntax issues, but any other similar extension can also be used.

For MDX files inside the /src/pages directory

Exporting Layout in MDX files inside the pages directory is necessary.

• Please note that this section is only for the MDX files presented inside the /src/pages directory.
• The latest update in the mdx plugin deprecated the defaultLayout option. So all the mdx files (only inside the pages directory) need to export a default Layout component (or wrap the whole file's content in the layout component), according to the mdx v2 syntax.
• From now on, if there is a need to create an mdx file inside the pages directory (so that it has its own route like /contact), please take a look at any of the previously presented files in the pages directory and just copy the lines related to exporting the layout. These are the lines that are added to all the mdx files in the pages directory:

import DefaultLayoutNarrow from "@/components/default-layout-narrow";

export default function Layout({ children }) {
  return <DefaultLayoutNarrow>{children}</DefaultLayoutNarrow>;
}