How to Fix Docusaurus MDX Components

In this tutorial, you'll learn about How to Fix Docusaurus MDX Components. We cover key concepts, practical examples, and best practices.

Custom React components in Docusaurus MDX files do not render — they show as raw text or cause build errors. MDX imports and component registration need correct setup.

The Wrong Way

// Importing a component in MDX
import Button from './components/Button'
<Button>Click me</Button>

If `./components/Button` does not exist or is not a valid React component, the MDX parser throws an error.

## The Right Way

### Step 1: Create a reusable component

```jsx
// src/components/Button.jsx
export default function Button({ children, color }) {
  return <button style={{ backgroundColor: color }}>{children}</button>;
}

### Step 2: Import in MDX correctly

```mdx
---
title: Using MDX Components
---

import Button from '@site/src/components/Button';

<Button color="#4A90D9">Click me</Button>

Use @site alias instead of relative paths for reliable imports.

Step 3: Register global MDX components

// docusaurus.config.js
module.exports = {
  presets: [
    [
      '"@docusaurus"/preset-classic',
      {
        docs: {
          remarkPlugins: [],
          rehypePlugins: [],
        },
      },
    ],
  ],
};

For global components available in all MDX files without explicit imports:

// src/theme/MDXComponents.js
import Button from '@site/src/components/Button';
export default {
  Button,
};

Step 4: Handle JSX in MDX

{/* This is a JSX expression inside MDX */}
{2 + 2} {/* renders as 4 */}

{/* Conditional rendering */}
{props.show && <Button>Conditional button</Button>}

Custom MDX component "Button" renders in docs — styled with props, no import errors.

Prevention

• Register frequently used components globally via MDXComponents.js to avoid repeated imports.
• Keep components in src/components/ and use @site alias.
• The component import pattern is the same as Doda Browser's extension API — global registration avoids redundant imports.

Common Mistakes with mdx components

1. Misunderstanding that String is [Char] with poor performance for large text operations
2. Using foldl instead of foldl' causing stack overflow on large lists
3. Forgetting deriving (Show, Eq) on custom data types needed for debugging

These mistakes appear frequently in real-world DOCUSAURUS code. DodaTech's contributors have identified these patterns through analysis of open-source projects and production systems.

Practice Exercise

Write a pure function that safely divides two integers using Maybe, then test it with edge cases like division by zero and negative numbers.

This exercise reinforces the concepts covered in this guide. Try implementing it before checking online solutions.

FAQ