Overview

Ready to take your API documentation from good to game-changing? Custom MDX components are your secret weapon! With our new component builder, you can create reusable, interactive elements that make your docs more engaging, consistent, and developer-friendly.

Why Custom Components Will Transform Your Docs

Here's why they're worth getting excited about:

🔄 Create Once, Use Everywhere

Build a component once and use it across all your documentation. Need to make changes? Update it in one place, and the changes propagate everywhere it's used.

🧱 Consistency That Scales

As your API and team grow, maintaining consistent documentation becomes challenging. Custom components ensure that your docs maintain the same look, feel, and behavior—no matter who's writing them.

💪 Advanced Functionality Made Simple

Complex documentation elements like toggleable content, tabbed interfaces, or content cards are notoriously difficult to build with standard Markdown. With custom components, these become reusable patterns that anyone on your team can implement.

🎮 Interactive Developer Experience

Custom components let you create interactive experiences that help developers understand your API faster and more thoroughly.

Getting Started With Custom Components

ReadMe's component builder makes creating custom MDX components straightforward, even if you're not a React expert. Here's how to get started:

1. Access the Component Builder

   • Navigate to the Content menu in the top navigation
   • Select Custom Components from the sidebar menu
   • Click the Create New button to open the component editor

2. Write Your Component

   • Use the code editor to write your component using JSX
   • See your component render in real-time in the preview panel
   • Test different content to ensure your component works as expected

3. Save and Reuse

   • Give your component a descriptive name
   • Save it to your component library
   • Use it throughout your documentation by inserting it into your MDX content

Your First Custom Component: A Step-by-Step Walkthrough

Let's break down how to create a simple but useful custom component. We'll build a "Note" component that makes important information stand out in your docs.

export const ExampleComponent = props => {
  return (
    <div className="flex items-center h-full w-full">
      <div className="bg-gray-800 rounded-md p-6 m-4">
        {props.children}
      </div>
    </div>
  );
};

<ExampleComponent>
  Here's a very simple example component rather than an empty state. This should help you figure out what's happening quicker and see what's possible with custom components!
</ExampleComponent>

Understanding the Code

Line 1: export const ExampleComponent = props => {

• Here we're defining a new component called ExampleComponent
• The export keyword is required to define any variable or component in MDX
• We can access the React props to render any attributes or content added to the component tag

Lines 2-8: The component's structure

• return (...) defines what the component will render when used
• The outer <div> uses Tailwind classes to center its content (flex items-center) and take up full width and height (h-full w-full)
• The inner <div> creates a dark gray box (bg-gray-800) with rounded corners (rounded-md) and spacing (p-6 m-4)
• {props.children} is the magic ingredient — it renders whatever content you place between your component tags

📘

A Quick Note on Tailwind CSS

Don't worry if these classes look unfamiliar! You can reference the official Tailwind CSS docs for a comprehensive guide on styling with utility clas

Lines 10-14: Using the component

• <ExampleComponent> opens the component
• The text between the tags becomes the children prop
• </ExampleComponent> closes the component

This simple example creates a reusable styled container that you can use throughout your documentation. Just wrap any content with <ExampleComponent> tags, and it will appear in a nice dark gray box with proper spacing and rounded corners!

Recipe

See the recipe below to walk through the code!

What makes this powerful? You can now use this component anywhere in your documentation where you need to highlight content in a consistent way. Need to change how highlighted content looks across your entire documentation? Just update the component once, and the changes apply everywhere you've used it!

Share Your Components with the Community

Created an awesome component that makes your docs shine? Don't keep that genius to yourself! Our Component Marketplace is where the magic of community happens.

Why Share Your Components?

• Help Fellow Developers — Your solution might be exactly what someone else is looking for
• Get Feedback — Improve your components with insights from the community
• Build Your Reputation — Showcase your skills and contribute to the broader documentation ecosystem

Just click "Browse Marketplace" to explore community-created components or submit your own. Together, we're building better docs one component at a time! 🚀