@docusaurus/mdx-loader

What is @docusaurus/mdx-loader?

@docusaurus/mdx-loader is a webpack loader for MDX (Markdown with JSX) files, specifically designed to work with Docusaurus, a static site generator. It allows you to write content in Markdown and embed React components within that content.

What are @docusaurus/mdx-loader's main functionalities?

Loading MDX files

This feature allows you to load and process MDX files using webpack. The loader converts MDX content into React components, enabling you to use Markdown and JSX together.

module.exports = {
  module: {
    rules: [
      {
        test: /\.mdx?$/,
        use: [
          {
            loader: '@docusaurus/mdx-loader',
            options: {
              // Options for the loader
            },
          },
        ],
      },
    ],
  },
};

Customizing MDX processing

This feature allows you to customize the MDX processing by adding remark and rehype plugins. In this example, the loader is configured to use 'remark-math' and 'rehype-katex' plugins for rendering mathematical expressions.

module.exports = {
  module: {
    rules: [
      {
        test: /\.mdx?$/,
        use: [
          {
            loader: '@docusaurus/mdx-loader',
            options: {
              remarkPlugins: [require('remark-math')],
              rehypePlugins: [require('rehype-katex')],
            },
          },
        ],
      },
    ],
  },
};

Other packages similar to @docusaurus/mdx-loader

mdx-loader

mdx-loader is a webpack loader for MDX files, similar to @docusaurus/mdx-loader but not specifically tailored for Docusaurus. It allows you to use MDX in any webpack-based project.

gatsby-plugin-mdx

gatsby-plugin-mdx is a plugin for Gatsby that enables the use of MDX in Gatsby projects. It provides similar functionality to @docusaurus/mdx-loader but is designed to work within the Gatsby ecosystem.

next-mdx-remote

next-mdx-remote is a library for using MDX with Next.js. It allows you to load MDX content remotely and render it in Next.js pages, providing similar capabilities to @docusaurus/mdx-loader but for the Next.js framework.

README

@docusaurus/mdx-loader

Docusaurus webpack loader for MDX.

Installation

yarn add @docusaurus/mdx-loader

Usage

// ...
module: {
  rules: [
    // ...
    {
      test: /\.mdx?$/,
      use: [
        {
          loader: '@docusaurus/mdx-loader',
          options: {
            // .. See options
          },
        },
      ],
    },
  ];
}

Options

rehypePlugins

Array of rehype plugins to manipulate the MDXHAST

remarkPlugins

Array of remark plugins to manipulate the MDXAST

metadataPath

A function to provide the metadataPath depending on current loaded MDX path that will be exported as the MDX metadata.

markdownConfig

The global Docusaurus Markdown config (config.markdown), that plugin authors should forward:

const loader = {
  loader: require.resolve('@docusaurus/mdx-loader'),
  options: {
    markdownConfig: siteConfig.markdown,
  },
};

Changelog

3.7.0 (2025-01-03)

:rocket: New Feature

• docusaurus-faster, docusaurus
  • #10800 feat(core): Turn Rspack incremental on by default (again) (@slorber)
• docusaurus-plugin-content-blog, docusaurus-theme-classic
  • #10768 feat(blog): Add author social icons for bluesky, mastodon, threads, twitch, youtube, instagram (@GingerGeek)
• create-docusaurus, docusaurus-mdx-loader, docusaurus-module-type-aliases, docusaurus-plugin-client-redirects, docusaurus-plugin-content-blog, docusaurus-plugin-content-docs, docusaurus-plugin-content-pages, docusaurus-plugin-debug, docusaurus-plugin-google-analytics, docusaurus-plugin-google-gtag, docusaurus-plugin-google-tag-manager, docusaurus-plugin-ideal-image, docusaurus-plugin-pwa, docusaurus-plugin-rsdoctor, docusaurus-plugin-sitemap, docusaurus-plugin-svgr, docusaurus-plugin-vercel-analytics, docusaurus-preset-classic, docusaurus-theme-classic, docusaurus-theme-common, docusaurus-theme-live-codeblock, docusaurus-theme-mermaid, docusaurus-theme-search-algolia, docusaurus-types, docusaurus
  • #10763 feat: Add React 19 support to Docusaurus v3 (@slorber)
• docusaurus-plugin-content-blog
  • #10729 feat(blog): Add frontMatter.sidebar_label (@slorber)
• docusaurus-module-type-aliases, docusaurus-plugin-svgr, docusaurus-preset-classic, docusaurus-types, docusaurus-utils, docusaurus
  • #10677 feat(svgr): create new Docusaurus SVGR plugin (@slorber)

:bug: Bug Fix

• docusaurus-remark-plugin-npm2yarn
  • #10803 fix(npm-to-yarn): add missing npm-to-yarn converter for Bun (@Lehoczky)
• docusaurus-theme-classic, docusaurus-theme-common
  • #10796 fix(theme): Footer Column/Link should merge provided className (@slorber)
• docusaurus-bundler, docusaurus-theme-common
  • #10786 fix(core): fix React hydration errors, change html minifier settings (@slorber)
• docusaurus-theme-common
  • #10782 fix(theme-common): code block magic comments should support SQL block comments (@WillBlack403)
• docusaurus-theme-translations
  • #10783 fix(theme-translations): Add missing Dutch (nl) theme translations (@janaukema)
  • #10760 fix(theme-translation): add missing Korean (ko) theme translations (@effozen)
• docusaurus-plugin-content-docs
  • #10754 fix(docs): fix sidebar item visibility bug for category index (@slorber)
• docusaurus
  • #10727 fix(core): fix codegen routesChunkName possible hash collision (@slorber)
• docusaurus-mdx-loader
  • #10723 fix(mdx-loader): fix md image paths with spaces bug related to transformImage encoding problem (@slorber)

:memo: Documentation

• #10740 docs: Link initialization docs together (@waldyrious)

:robot: Dependencies

• #10771 chore(deps): bump nanoid from 3.3.7 to 3.3.8 (@dependabot[bot])
• #10721 chore(deps): bump actions/dependency-review-action from 4.4.0 to 4.5.0 (@dependabot[bot])

:wrench: Maintenance

• Other
  • #10770 chore: Devcontainer upgrade to Ubuntu Noble & Node 22 (@GingerGeek)
• docusaurus-theme-search-algolia
  • #10801 refactor(algolia): simplify SearchBar component (@slorber)
  • #10672 chore(algolia): upgrade algoliasearch to v5 (@millotp)
• docusaurus
  • #10798 refactor(core): Use Intl native API to get locale direction, remove rtl-detect depend… (@slorber)
  • #10747 refactor(core): swizzle wrap should use ReactNode instead of JSX.Element (@slorber)
• create-docusaurus, docusaurus-mdx-loader, docusaurus-module-type-aliases, docusaurus-plugin-content-blog, docusaurus-plugin-content-docs, docusaurus-plugin-content-pages, docusaurus-plugin-debug, docusaurus-plugin-ideal-image, docusaurus-plugin-pwa, docusaurus-theme-classic, docusaurus-theme-common, docusaurus-theme-live-codeblock, docusaurus-theme-mermaid, docusaurus-theme-search-algolia, docusaurus-types, docusaurus
  • #10746 refactor: prepare types for React 19 (@slorber)
• docusaurus-theme-common
  • #10728 refactor(theme-common): change storageUtils useSyncExternalCode getSnapshot workaround (@slorber)

Committers: 14

• Alvin Bryan (@alvinometric)
• Hichem Fantar (@hichemfantar)
• Ivan Cheban (@ivancheban)
• Jake Boone (@jakeboone02)
• Jan Aukema (@janaukema)
• Lehoczky Zoltán (@Lehoczky)
• Lin Huang (@codimiracle)
• Pierre Millot (@millotp)
• Sébastien Lorber (@slorber)
• Taylor Reece (@taylorreece)
• Waldir Pimenta (@waldyrious)
• William Black (@WillBlack403)
• Zed Spencer-Milnes (@GingerGeek)
• Zen (@effozen)