Explainer
← Back to writing

A deep dive into Explainer's MDX components

Explainer v2 ships with a rich library of auto-imported MDX components — callouts, cards, steps, code groups, and more. Learn how they work and how to use them effectively to create engaging documentation.

Published March 13, 2026

tutorial mdx components documentation

One of Explainer’s greatest strengths is its MDX component library. Every component is auto-imported — no import statements needed — so you can focus on writing content, not boilerplate.

In this article, we’ll walk through each component family, show practical examples, and share tips to get the most out of them.

Callouts: guide your reader’s attention

Callouts are the quickest way to highlight important information. Explainer supports five variants, each with a distinct visual style and semantic meaning.

When to use callouts

Use callouts sparingly. When everything is highlighted, nothing is. Reserve them for genuinely important notes, warnings, or tips that readers shouldn’t miss.

The syntax is straightforward:

:::callout{variant="warning" title="Breaking change"}
The `config.legacy` option has been removed in v2.
:::

Available variants: info, success, warning, danger, and note. Each maps to a specific color scheme that works in both light and dark modes.

Pro tip

You can omit the title attribute for a more compact callout — perfect for short one-liner notes.

Cards and Card Groups: structured navigation

Cards are perfect for feature overviews, link collections, or any content that benefits from a visual grid layout.

Simple syntax

Write cards with a single directive — no JSX knowledge required.

Responsive grid

Card groups automatically adapt from 1 to 3 columns based on screen size.

Icons included

Use any Lucide icon by name. They render inline with the card label.

The cols attribute on card-group controls the maximum number of columns. Cards with an href attribute become clickable links.

::::card-group{cols=2}
:::card{label="Getting Started" icon="lucide:rocket" href="/en/explainer/getting-started"}
Set up Explainer in under 5 minutes.
:::

:::card{label="Configuration" icon="lucide:settings" href="/en/explainer/configuration"}
Customize every aspect of your documentation.
:::
::::

Steps: sequential instructions

When documenting a process, steps provide a clear visual hierarchy with numbered indicators.

Write your content

Create .mdx files in the content directory. Explainer auto-discovers them and builds the navigation.

Use directives freely

Add callouts, cards, code blocks — all auto-imported. No setup required.

Build and deploy

Run pnpm build and deploy the static output anywhere. That’s it.

Steps are especially useful for getting-started guides, installation instructions, and multi-stage tutorials.

Code Groups: compare and contrast

Code groups let you show multiple code blocks in a tabbed interface — ideal for showing the same concept in different languages or configurations.

TypeScript
interface User {
  name: string
  email: string
}
Python
class User:
    name: str
    email: str
Go
type User struct {
    Name  string
    Email string
}

The tab labels are extracted from the [label] syntax in each code block’s meta string. Readers can switch between tabs without losing their scroll position.

Rich code blocks

Beyond code groups, Explainer’s code blocks support several enhancements out of the box:

  • Syntax highlighting with dual themes (light and dark)
  • Line numbers for reference
  • Title bars showing the file name
  • Line highlighting to draw attention to specific lines
  • 60+ language icons displayed automatically
export async function fetchContributors(options?: FetchContributorsOptions): Promise<Contributor[]> {
  const owner = options?.owner ?? 'LeadcodeDev'
  const repo = options?.repo ?? 'explainer_v2'

  const response = await fetch(
    `https://api.github.com/repos/${owner}/${repo}/contributors?per_page=100`,
    { headers },
  )

  return response.json()
}

Combining components

The real power comes from combining components together. Here’s a pattern we use frequently in the Explainer docs:

Prerequisites

Make sure you have Node.js 22+ and pnpm installed before continuing.

Clone and install 

git clone https://github.com/LeadcodeDev/explainer_v2
cd explainer_v2 && pnpm install

Start the dev server 

pnpm dev

All three apps start simultaneously — docs on :4321, blog on :4322, website on :4323.

:::

What’s next

These components cover the most common documentation patterns. If you need something custom, Explainer’s MDX pipeline supports standard React components too — just import and use them.

Explore the full reference

Every component is documented in detail in the MDX Components section of the docs, with live examples and all available props.

We’d love to see what you build with these components. Share your documentation with us on GitHub!