Reusable Content in MDX

Stop copy-pasting the same content across docs. Learn partials, shared snippets, composable templates, content variables, and conditional content in MDX.

You know that install block you've copy-pasted into 20 different docs pages? Or that warning callout you keep rewriting slightly differently each time?

Stop doing that. MDX lets you write content once and reuse it everywhere — through partials, snippets, templates, and variables. When something changes (and it will), you update one file instead of hunting through dozens.

Content Partials

Partials are small MDX files containing a chunk of content. Import them, drop them in, done.

Creating Partials

mdx example

{/* partials/_install-node.mdx */}

## Prerequisites

Make sure you have Node.js 18+ installed:

node --version # Should output v18.0.0 or higher

Example

If you need to install or update Node.js, visit [nodejs.org](https://nodejs.org) or use a version manager like [nvm](https://github.com/nvm-sh/nvm):

nvm install 18 nvm use 18

Example

mdx example

{/* partials/_typescript-config.mdx */}

### TypeScript Configuration

Add the following to your `tsconfig.json`:

{ "compilerOptions": { "target": "ES2020", "module": "ESNext", "moduleResolution": "bundler", "jsx": "react-jsx", "strict": true, "esModuleInterop": true, "skipLibCheck": true } }

Example

Using Partials

Now any guide can pull those in:

mdx example

{/* guides/getting-started.mdx */}
import InstallNode from '../partials/_install-node.mdx';
import TypeScriptConfig from '../partials/_typescript-config.mdx';

# Getting Started

Follow these steps to set up your development environment.

<InstallNode />

## Installation

npm install my-library

Example

<TypeScriptConfig /> Now you're ready to start building!

Parameterized Partials

Need the same pattern with different data? Pass props:

Example

{/* partials/PackageInstall.jsx */} import React from 'react'; export default function PackageInstall({ name, dev = false, extras = [] }) { const packages = [name, ...extras].join(' '); const devFlag = dev ? ' -D' : ''; return ( <div className="install-commands"> <h4>Installation</h4> <p>Install <code>{name}</code> using your preferred package manager:</p> <div className="tabs"> <div className="tab" data-label="npm"> <pre><code>{`npm install${devFlag} ${packages}`}</code></pre> </div> <div className="tab" data-label="yarn"> <pre><code>{`yarn add${dev ? ' --dev' : ''} ${packages}`}</code></pre> </div> <div className="tab" data-label="pnpm"> <pre><code>{`pnpm add${devFlag} ${packages}`}</code></pre> </div> <div className="tab" data-label="bun"> <pre><code>{`bun add${devFlag} ${packages}`}</code></pre> </div> </div> </div> ); }

Example

import PackageInstall from '../partials/PackageInstall'; <PackageInstall name="@mdx-js/mdx" extras={["@mdx-js/react"]} /> <PackageInstall name="eslint" dev={true} extras={["prettier", "eslint-config-next"]} />

One component, any package, every package manager. No more maintaining four separate install blocks.

Shared Snippets

Snippets are smaller than partials — think callouts, badges, API endpoint labels. Tiny reusable pieces you drop in everywhere.

Example

// snippets/Callout.jsx import React from 'react'; const icons = { info: 'ℹ️', warning: '⚠️', danger: '🚨', tip: '💡', note: '📝', }; const colors = { info: 'border-blue-400 bg-blue-50 dark:bg-blue-950', warning: 'border-yellow-400 bg-yellow-50 dark:bg-yellow-950', danger: 'border-red-400 bg-red-50 dark:bg-red-950', tip: 'border-green-400 bg-green-50 dark:bg-green-950', note: 'border-gray-400 bg-gray-50 dark:bg-gray-900', }; export function Callout({ type = 'info', title, children }) { return ( <div className={`callout border-l-4 p-4 my-4 rounded-r-lg ${colors[type]}`}> <div className="flex items-center gap-2 font-semibold mb-1"> <span>{icons[type]}</span> <span>{title || type.charAt(0).toUpperCase() + type.slice(1)}</span> </div> <div className="callout-content text-sm">{children}</div> </div> ); }

Example

// snippets/VersionBadge.jsx export function VersionBadge({ version, status = 'stable' }) { const statusColors = { stable: 'bg-green-100 text-green-800', beta: 'bg-yellow-100 text-yellow-800', deprecated: 'bg-red-100 text-red-800', experimental: 'bg-purple-100 text-purple-800', }; return ( <span className={`inline-flex items-center px-2 py-0.5 rounded text-xs font-medium ${statusColors[status]}`}> v{version} ({status}) </span> ); }

Example

// snippets/ApiEndpoint.jsx export function ApiEndpoint({ method, path, auth = false }) { const methodColors = { GET: 'bg-green-500', POST: 'bg-blue-500', PUT: 'bg-orange-500', DELETE: 'bg-red-500', PATCH: 'bg-purple-500', }; return ( <div className="flex items-center gap-3 p-3 bg-gray-100 dark:bg-gray-800 rounded-lg my-4 font-mono text-sm"> <span className={`${methodColors[method]} text-white px-2 py-0.5 rounded font-bold text-xs`}> {method} </span> <code className="flex-1">{path}</code> {auth && <span className="text-xs text-gray-500">🔐 Auth required</span>} </div> ); }

Global Snippet Registration

jsx example

// mdx-components.jsx (Next.js App Router)
import { Callout } from './snippets/Callout';
import { VersionBadge } from './snippets/VersionBadge';
import { ApiEndpoint } from './snippets/ApiEndpoint';

export function useMDXComponents(components) {
  return {
    Callout,
    VersionBadge,
    ApiEndpoint,
    ...components,
  };
}

Now just use them anywhere — no imports needed:

mdx example

# User API <VersionBadge version="2.1.0" status="stable" />

<ApiEndpoint method="GET" path="/api/v2/users/:id" auth={true} />

<Callout type="warning" title="Rate Limited">
  This endpoint is limited to 100 requests per minute per API key.
</Callout>

Component Composition for Content Reuse

Feature Comparison Tables

Instead of maintaining markdown tables that get out of sync, use a data-driven component:

Example

// components/FeatureTable.jsx export function FeatureTable({ features }) { return ( <table className="w-full border-collapse"> <thead> <tr> <th className="text-left p-2">Feature</th> <th className="text-center p-2">Free</th> <th className="text-center p-2">Pro</th> <th className="text-center p-2">Enterprise</th> </tr> </thead> <tbody> {features.map(({ name, free, pro, enterprise }) => ( <tr key={name} className="border-t"> <td className="p-2">{name}</td> <td className="text-center p-2">{free ? '✅' : '❌'}</td> <td className="text-center p-2">{pro ? '✅' : '❌'}</td> <td className="text-center p-2">{enterprise ? '✅' : '❌'}</td> </tr> ))} </tbody> </table> ); }

Example

import { FeatureTable } from '../components/FeatureTable'; <FeatureTable features={[ { name: "Basic Auth", free: true, pro: true, enterprise: true }, { name: "SSO Integration", free: false, pro: true, enterprise: true }, { name: "Audit Logs", free: false, pro: false, enterprise: true }, { name: "Custom Roles", free: false, pro: true, enterprise: true }, { name: "SLA Guarantee", free: false, pro: false, enterprise: true }, ]} />

Step-by-Step Reusable Pattern

Numbered steps show up all over docs. Build them once:

Example

// components/Steps.jsx export function Steps({ children }) { return ( <div className="steps-container relative pl-8 border-l-2 border-blue-200"> {children} </div> ); } export function Step({ number, title, children }) { return ( <div className="step relative pb-8 last:pb-0"> <div className="absolute -left-[2.45rem] w-6 h-6 rounded-full bg-blue-500 text-white text-xs flex items-center justify-center font-bold"> {number} </div> <h4 className="font-semibold text-lg mb-2">{title}</h4> <div className="text-gray-700 dark:text-gray-300">{children}</div> </div> ); }

mdx example

<Steps>
  <Step number={1} title="Install Dependencies">
    Run the installation command for your package manager.
  </Step>
  <Step number={2} title="Configure Your Project">
    Add the configuration file to your project root.
  </Step>
  <Step number={3} title="Start Development Server">
    Launch the dev server and open your browser.
  </Step>
</Steps>

Template Patterns

Documentation Page Template

If every API page has the same structure (title, version badge, deprecation notice, content), make it a template:

jsx example

// templates/DocTemplate.jsx
import { Callout } from '../snippets/Callout';
import { VersionBadge } from '../snippets/VersionBadge';
import { ApiEndpoint } from '../snippets/ApiEndpoint';

export function DocTemplate({
  title,
  version,
  status,
  description,
  since,
  deprecated,
  children,
}) {
  return (
    <article>
      <header className="mb-8">
        <div className="flex items-center gap-3">
          <h1 className="text-3xl font-bold">{title}</h1>
          {version && <VersionBadge version={version} status={status} />}
        </div>
        {description && <p className="text-lg text-gray-600 mt-2">{description}</p>}
        {since && <p className="text-sm text-gray-500">Available since v{since}</p>}
      </header>

      {deprecated && (
        <Callout type="danger" title="Deprecated">
          This feature is deprecated and will be removed in a future version.
          {deprecated.alternative && (
            <span> Use <code>{deprecated.alternative}</code> instead.</span>
          )}
        </Callout>
      )}

      <div className="doc-content prose prose-lg">
        {children}
      </div>
    </article>
  );
}

Content Variables

Define your product name, version, and URLs in one place. When the version bumps, you change one file:

jsx example

// content/variables.js
export const PRODUCT_NAME = 'AcmeDocs';
export const CURRENT_VERSION = '3.2.1';
export const MIN_NODE_VERSION = '18.0.0';
export const GITHUB_URL = 'https://github.com/acme/acmedocs';
export const DOCS_URL = 'https://docs.acme.com';
export const SUPPORT_EMAIL = 'support@acme.com';

export const INSTALL_COMMAND = `npm install ${PRODUCT_NAME.toLowerCase()}@${CURRENT_VERSION}`;

export const LINKS = {
  quickstart: '/docs/quickstart',
  api: '/docs/api-reference',
  examples: '/docs/examples',
  changelog: '/docs/changelog',
};

mdx example

import { PRODUCT_NAME, CURRENT_VERSION, MIN_NODE_VERSION, INSTALL_COMMAND } from '../content/variables';

# Welcome to {PRODUCT_NAME}

You are reading the documentation for **{PRODUCT_NAME} v{CURRENT_VERSION}**.

## Requirements

- Node.js {MIN_NODE_VERSION} or higher
- npm 9+

## Quick Install

{INSTALL_COMMAND}

Example

Conditional Content Inclusion

Environment-Based Content

Show different content in dev vs production, or based on feature flags:

Example

// components/ConditionalContent.jsx export function IfEnv({ env, children }) { const currentEnv = process.env.DOCS_ENV || 'production'; if (currentEnv !== env) return null; return <>{children}</>; } export function IfFeatureFlag({ flag, children, fallback = null }) { const flags = getFeatureFlags(); // Your feature flag system if (!flags[flag]) return fallback; return <>{children}</>; } export function Platform({ only, children }) { // For client-side platform detection const [platform, setPlatform] = useState(null); useEffect(() => { const ua = navigator.userAgent; if (ua.includes('Mac')) setPlatform('mac'); else if (ua.includes('Win')) setPlatform('windows'); else setPlatform('linux'); }, []); if (only && platform !== only) return null; return <>{children}</>; }

mdx example

import { IfEnv, Platform } from '../components/ConditionalContent';

## Installation

<Platform only="mac">

brew install acmedocs

Example

</Platform> <Platform only="windows">

choco install acmedocs

Example

</Platform> <Platform only="linux">

curl -fsSL https://get.acme.com | bash

Example

</Platform> <IfEnv env="development"> > **Dev Note:** This section is only visible in development builds. > The internal API endpoint is `http://localhost:3001/api`. </IfEnv>

Audience-Based Content

Let readers self-select their experience level:

jsx example

// components/Audience.jsx
export function ForBeginners({ children }) {
  return (
    <details className="beginner-content border rounded-lg p-4 my-4">
      <summary className="cursor-pointer font-medium">
        📘 New to this concept? Expand for a beginner explanation
      </summary>
      <div className="mt-3">{children}</div>
    </details>
  );
}

export function ForAdvanced({ children }) {
  return (
    <details className="advanced-content border rounded-lg p-4 my-4">
      <summary className="cursor-pointer font-medium">
        🔬 Advanced Details
      </summary>
      <div className="mt-3">{children}</div>
    </details>
  );
}

DRY Principles Summary

Pattern	Use Case	Benefit
Content Partials	Multi-paragraph reusable blocks	Single source of truth
Snippets	Small inline elements (badges, callouts)	Consistent UI patterns
Template Components	Page structure patterns	Uniform documentation
Content Variables	Names, versions, URLs	Change once, update everywhere
Conditional Content	Platform/audience-specific text	Targeted documentation
Composition	Complex reusable layouts	Flexible building blocks

Before (Repetitive) vs After (DRY)

Before — duplicated in 20 files:

Example

> ⚠️ **Warning:** This feature requires Node.js 18 or higher. > Make sure to run `node --version` to verify your installation. > Visit [nodejs.org](https://nodejs.org) to download the latest version.

After — single source of truth:

mdx example

<Callout type="warning" title="Node.js Required">
  This feature requires Node.js {MIN_NODE_VERSION} or higher.
  Run `node --version` to verify your installation.
</Callout>

Rule of thumb: If you've pasted the same content into three places, it's time to make it a partial or component. Duplicated content rots fast — a single typo fix should only require changing one file.

Apply these patterns and your docs become a proper codebase: modular, easy to maintain, and consistent across hundreds of pages.

You know that install block you've copy-pasted into 20 different docs pages? Or that warning callout you keep rewriting slightly differently each time?

Content Partials

Partials are small MDX files containing a chunk of content. Import them, drop them in, done.

Creating Partials

mdx example

{/* partials/_install-node.mdx */}

## Prerequisites

Make sure you have Node.js 18+ installed:

node --version # Should output v18.0.0 or higher

Example

If you need to install or update Node.js, visit [nodejs.org](https://nodejs.org) or use a version manager like [nvm](https://github.com/nvm-sh/nvm):

nvm install 18 nvm use 18

Example

mdx example

{/* partials/_typescript-config.mdx */}

### TypeScript Configuration

Add the following to your `tsconfig.json`:

{ "compilerOptions": { "target": "ES2020", "module": "ESNext", "moduleResolution": "bundler", "jsx": "react-jsx", "strict": true, "esModuleInterop": true, "skipLibCheck": true } }

Example

Using Partials

Now any guide can pull those in:

mdx example

{/* guides/getting-started.mdx */}
import InstallNode from '../partials/_install-node.mdx';
import TypeScriptConfig from '../partials/_typescript-config.mdx';

# Getting Started

Follow these steps to set up your development environment.

<InstallNode />

## Installation

npm install my-library

Example

<TypeScriptConfig /> Now you're ready to start building!

Parameterized Partials

Need the same pattern with different data? Pass props:

Example

One component, any package, every package manager. No more maintaining four separate install blocks.

Shared Snippets

Snippets are smaller than partials — think callouts, badges, API endpoint labels. Tiny reusable pieces you drop in everywhere.

Example

Global Snippet Registration

jsx example

// mdx-components.jsx (Next.js App Router)
import { Callout } from './snippets/Callout';
import { VersionBadge } from './snippets/VersionBadge';
import { ApiEndpoint } from './snippets/ApiEndpoint';

export function useMDXComponents(components) {
  return {
    Callout,
    VersionBadge,
    ApiEndpoint,
    ...components,
  };
}

Now just use them anywhere — no imports needed:

mdx example

# User API <VersionBadge version="2.1.0" status="stable" />

<ApiEndpoint method="GET" path="/api/v2/users/:id" auth={true} />

<Callout type="warning" title="Rate Limited">
  This endpoint is limited to 100 requests per minute per API key.
</Callout>

Component Composition for Content Reuse

Feature Comparison Tables

Instead of maintaining markdown tables that get out of sync, use a data-driven component:

Example

Step-by-Step Reusable Pattern

Numbered steps show up all over docs. Build them once:

Example

mdx example

<Steps>
  <Step number={1} title="Install Dependencies">
    Run the installation command for your package manager.
  </Step>
  <Step number={2} title="Configure Your Project">
    Add the configuration file to your project root.
  </Step>
  <Step number={3} title="Start Development Server">
    Launch the dev server and open your browser.
  </Step>
</Steps>

Template Patterns

Documentation Page Template

If every API page has the same structure (title, version badge, deprecation notice, content), make it a template:

jsx example

// templates/DocTemplate.jsx
import { Callout } from '../snippets/Callout';
import { VersionBadge } from '../snippets/VersionBadge';
import { ApiEndpoint } from '../snippets/ApiEndpoint';

export function DocTemplate({
  title,
  version,
  status,
  description,
  since,
  deprecated,
  children,
}) {
  return (
    <article>
      <header className="mb-8">
        <div className="flex items-center gap-3">
          <h1 className="text-3xl font-bold">{title}</h1>
          {version && <VersionBadge version={version} status={status} />}
        </div>
        {description && <p className="text-lg text-gray-600 mt-2">{description}</p>}
        {since && <p className="text-sm text-gray-500">Available since v{since}</p>}
      </header>

      {deprecated && (
        <Callout type="danger" title="Deprecated">
          This feature is deprecated and will be removed in a future version.
          {deprecated.alternative && (
            <span> Use <code>{deprecated.alternative}</code> instead.</span>
          )}
        </Callout>
      )}

      <div className="doc-content prose prose-lg">
        {children}
      </div>
    </article>
  );
}

Content Variables

Define your product name, version, and URLs in one place. When the version bumps, you change one file:

jsx example

// content/variables.js
export const PRODUCT_NAME = 'AcmeDocs';
export const CURRENT_VERSION = '3.2.1';
export const MIN_NODE_VERSION = '18.0.0';
export const GITHUB_URL = 'https://github.com/acme/acmedocs';
export const DOCS_URL = 'https://docs.acme.com';
export const SUPPORT_EMAIL = 'support@acme.com';

export const INSTALL_COMMAND = `npm install ${PRODUCT_NAME.toLowerCase()}@${CURRENT_VERSION}`;

export const LINKS = {
  quickstart: '/docs/quickstart',
  api: '/docs/api-reference',
  examples: '/docs/examples',
  changelog: '/docs/changelog',
};

mdx example

import { PRODUCT_NAME, CURRENT_VERSION, MIN_NODE_VERSION, INSTALL_COMMAND } from '../content/variables';

# Welcome to {PRODUCT_NAME}

You are reading the documentation for **{PRODUCT_NAME} v{CURRENT_VERSION}**.

## Requirements

- Node.js {MIN_NODE_VERSION} or higher
- npm 9+

## Quick Install

{INSTALL_COMMAND}

Example

Conditional Content Inclusion

Environment-Based Content

Show different content in dev vs production, or based on feature flags:

Example

mdx example

import { IfEnv, Platform } from '../components/ConditionalContent';

## Installation

<Platform only="mac">

brew install acmedocs

Example

</Platform> <Platform only="windows">

choco install acmedocs

Example

</Platform> <Platform only="linux">

curl -fsSL https://get.acme.com | bash

Example

</Platform> <IfEnv env="development"> > **Dev Note:** This section is only visible in development builds. > The internal API endpoint is `http://localhost:3001/api`. </IfEnv>

Audience-Based Content

Let readers self-select their experience level:

jsx example

// components/Audience.jsx
export function ForBeginners({ children }) {
  return (
    <details className="beginner-content border rounded-lg p-4 my-4">
      <summary className="cursor-pointer font-medium">
        📘 New to this concept? Expand for a beginner explanation
      </summary>
      <div className="mt-3">{children}</div>
    </details>
  );
}

export function ForAdvanced({ children }) {
  return (
    <details className="advanced-content border rounded-lg p-4 my-4">
      <summary className="cursor-pointer font-medium">
        🔬 Advanced Details
      </summary>
      <div className="mt-3">{children}</div>
    </details>
  );
}

DRY Principles Summary

Pattern	Use Case	Benefit
Content Partials	Multi-paragraph reusable blocks	Single source of truth
Snippets	Small inline elements (badges, callouts)	Consistent UI patterns
Template Components	Page structure patterns	Uniform documentation
Content Variables	Names, versions, URLs	Change once, update everywhere
Conditional Content	Platform/audience-specific text	Targeted documentation
Composition	Complex reusable layouts	Flexible building blocks

Before (Repetitive) vs After (DRY)

Before — duplicated in 20 files:

Example

After — single source of truth:

mdx example

<Callout type="warning" title="Node.js Required">
  This feature requires Node.js {MIN_NODE_VERSION} or higher.
  Run `node --version` to verify your installation.
</Callout>

Rule of thumb: If you've pasted the same content into three places, it's time to make it a partial or component. Duplicated content rots fast — a single typo fix should only require changing one file.

Apply these patterns and your docs become a proper codebase: modular, easy to maintain, and consistent across hundreds of pages.

Reusable Content in MDX

Content Partials

Creating Partials

Using Partials

Parameterized Partials

Shared Snippets

Global Snippet Registration

Component Composition for Content Reuse

Feature Comparison Tables

Step-by-Step Reusable Pattern

Template Patterns

Documentation Page Template

Content Variables

Conditional Content Inclusion

Environment-Based Content

Audience-Based Content

DRY Principles Summary

Before (Repetitive) vs After (DRY)

Continue learning this concept

Reusable Content in MDX

Content Partials

Creating Partials

Using Partials

Parameterized Partials

Shared Snippets

Global Snippet Registration

Component Composition for Content Reuse

Feature Comparison Tables

Step-by-Step Reusable Pattern

Template Patterns

Documentation Page Template

Content Variables

Conditional Content Inclusion

Environment-Based Content

Audience-Based Content

DRY Principles Summary

Before (Repetitive) vs After (DRY)

Continue learning this concept