MDX Layouts

Wrap your MDX pages in consistent shells — headers, sidebars, footers. Learn how to build, nest, and conditionally swap layouts based on frontmatter.

Layouts wrap your MDX content in a consistent page structure. Think headers, footers, sidebars, nav — all applied automatically so you don't repeat yourself in every file.

How Layouts Work

A layout is just a React component. Your compiled MDX content gets passed in as children, and any frontmatter data comes along as props.

jsx example

// Basic layout concept
// Your MDX content becomes the children of the layout component
<Layout {...frontmatterProps}>
  <YourMDXContent />
</Layout>

That's it. Nothing magical.

Creating Layout Components

Basic Layout

jsx example

// layouts/BaseLayout.jsx
import React from 'react';
import Header from '../components/Header';
import Footer from '../components/Footer';
import SEO from '../components/SEO';

export default function BaseLayout({ children, title, description, author }) {
  return (
    <div className="base-layout">
      <SEO title={title} description={description} />
      <Header />
      <main className="content-wrapper">
        <article className="prose prose-lg max-w-4xl mx-auto py-8">
          {title && <h1 className="page-title">{title}</h1>}
          {author && (
            <p className="text-gray-600 text-sm">By {author}</p>
          )}
          {children}
        </article>
      </main>
      <Footer />
    </div>
  );
}

Using a Layout via Export

In your MDX file, set the layout with a default export:

Example

import BaseLayout from '../layouts/BaseLayout'; export default ({ children, ...props }) => ( <BaseLayout {...props}>{children}</BaseLayout> ); # My Article This content will be wrapped by BaseLayout automatically.

Using a Layout via Configuration

With frameworks like Next.js, you can set layouts globally instead of per-file:

Example

// next.config.js (Next.js with @next/mdx) const withMDX = require('@next/mdx')({ extension: /\.mdx?$/, options: { providerImportSource: '@mdx-js/react', }, }); module.exports = withMDX({ pageExtensions: ['js', 'jsx', 'md', 'mdx'], });

Example

// pages/_app.jsx - Global MDX layout via provider import { MDXProvider } from '@mdx-js/react'; import DefaultLayout from '../layouts/DefaultLayout'; const components = { wrapper: ({ children, ...props }) => ( <DefaultLayout {...props}>{children}</DefaultLayout> ), }; export default function App({ Component, pageProps }) { return ( <MDXProvider components={components}> <Component {...pageProps} /> </MDXProvider> ); }

Nested Layouts

You can stack layouts. A base layout handles the global shell, while a docs layout adds a sidebar. They compose together.

jsx example

// layouts/DocsLayout.jsx
import React from 'react';
import BaseLayout from './BaseLayout';
import Sidebar from '../components/Sidebar';
import TableOfContents from '../components/TableOfContents';
import Breadcrumbs from '../components/Breadcrumbs';

export default function DocsLayout({ children, title, description, toc }) {
  return (
    <BaseLayout title={title} description={description}>
      <div className="docs-container flex gap-8">
        {/* Left Sidebar - Navigation */}
        <aside className="w-64 shrink-0 hidden lg:block">
          <Sidebar />
        </aside>

        {/* Main Content */}
        <div className="flex-1 min-w-0">
          <Breadcrumbs />
          <div className="docs-content">
            {children}
          </div>
        </div>

        {/* Right Sidebar - Table of Contents */}
        <aside className="w-56 shrink-0 hidden xl:block">
          <TableOfContents items={toc} />
        </aside>
      </div>
    </BaseLayout>
  );
}

Example

// layouts/BlogLayout.jsx - Another nested layout import React from 'react'; import BaseLayout from './BaseLayout'; import AuthorCard from '../components/AuthorCard'; import ShareButtons from '../components/ShareButtons'; import RelatedPosts from '../components/RelatedPosts'; export default function BlogLayout({ children, title, description, author, date, tags, readingTime, }) { return ( <BaseLayout title={title} description={description}> <article className="blog-post max-w-3xl mx-auto"> <header className="mb-8"> <h1 className="text-4xl font-bold">{title}</h1> <div className="flex items-center gap-4 mt-4 text-gray-600"> <time dateTime={date}>{new Date(date).toLocaleDateString()}</time> <span>·</span> <span>{readingTime} min read</span> </div> {tags && ( <div className="flex gap-2 mt-3"> {tags.map(tag => ( <span key={tag} className="px-2 py-1 bg-blue-100 text-blue-800 rounded text-sm"> {tag} </span> ))} </div> )} </header> <div className="prose prose-lg"> {children} </div> <footer className="mt-12 border-t pt-8"> <ShareButtons title={title} /> <AuthorCard author={author} /> <RelatedPosts tags={tags} /> </footer> </article> </BaseLayout> ); }

Layout Props and Frontmatter

Frontmatter data flows straight into your layout as props. You can control layout behavior from the MDX file itself:

mdx example

Your content here receives the layout specified in frontmatter...

Then you resolve which layout to use:

Example

// layouts/LayoutResolver.jsx import DocsLayout from './DocsLayout'; import BlogLayout from './BlogLayout'; import LandingLayout from './LandingLayout'; import MinimalLayout from './MinimalLayout'; const layoutMap = { docs: DocsLayout, blog: BlogLayout, landing: LandingLayout, minimal: MinimalLayout, }; export default function LayoutResolver({ children, layout = 'docs', ...props }) { const LayoutComponent = layoutMap[layout] || layoutMap.docs; return <LayoutComponent {...props}>{children}</LayoutComponent>; }

Conditional Layouts Based on Frontmatter

You can pick layouts dynamically based on what's in the frontmatter:

Example

// utils/getLayout.js export function getLayout(frontmatter) { const { layout, draft, type } = frontmatter; // Draft content gets a preview layout with warnings if (draft) { return 'preview'; } // Explicit layout takes priority if (layout) { return layout; } // Infer from content type switch (type) { case 'api-reference': return 'api'; case 'tutorial': return 'tutorial'; case 'changelog': return 'minimal'; default: return 'docs'; } }

jsx example

// Conditional layout with feature flags
export default function SmartLayout({ children, ...props }) {
  const { sidebar = true, toc = true, fullWidth = false, theme } = props;

  return (
    <div className={`layout ${theme === 'dark' ? 'dark' : ''}`}>
      <div className={`flex ${fullWidth ? 'max-w-full' : 'max-w-7xl mx-auto'}`}>
        {sidebar && <Sidebar />}
        <main className="flex-1 px-6 py-8">
          {children}
        </main>
        {toc && <TableOfContents />}
      </div>
    </div>
  );
}

Layout Composition Patterns

Higher-Order Layout Pattern

A factory function that spits out configured layouts:

jsx example

// createLayout.js - Layout factory
export function createLayout(options = {}) {
  const {
    showHeader = true,
    showFooter = true,
    showSidebar = false,
    maxWidth = '4xl',
    padding = '8',
  } = options;

  return function ComposedLayout({ children, ...props }) {
    return (
      <div className="min-h-screen flex flex-col">
        {showHeader && <Header {...props} />}
        <div className="flex flex-1">
          {showSidebar && <Sidebar {...props} />}
          <main className={`flex-1 max-w-${maxWidth} mx-auto p-${padding}`}>
            {children}
          </main>
        </div>
        {showFooter && <Footer />}
      </div>
    );
  };
}

// Usage
const DocsLayout = createLayout({ showSidebar: true, maxWidth: '6xl' });
const BlogLayout = createLayout({ maxWidth: '3xl', padding: '12' });
const LandingLayout = createLayout({ showSidebar: false, showFooter: true, maxWidth: 'full' });

Slot-Based Layout Pattern

Let MDX pages inject content into specific regions:

Example

// layouts/SlotLayout.jsx export default function SlotLayout({ children, header, sidebar, footer, ...props }) { return ( <div className="slot-layout"> <div className="layout-header"> {header || <DefaultHeader {...props} />} </div> <div className="layout-body flex"> {sidebar && ( <aside className="layout-sidebar w-64"> {sidebar} </aside> )} <main className="layout-content flex-1"> {children} </main> </div> <div className="layout-footer"> {footer || <DefaultFooter />} </div> </div> ); }

Passing Data to Layouts

Via Context Providers

jsx example

// layouts/DataLayout.jsx
import { createContext, useContext } from 'react';

const LayoutContext = createContext({});

export function useLayoutData() {
  return useContext(LayoutContext);
}

export default function DataLayout({ children, ...frontmatter }) {
  const layoutData = {
    ...frontmatter,
    breadcrumbs: generateBreadcrumbs(frontmatter.slug),
    navigation: getNavigation(frontmatter.section),
    editUrl: `https://github.com/repo/edit/main/docs/${frontmatter.slug}.mdx`,
  };

  return (
    <LayoutContext.Provider value={layoutData}>
      <div className="data-layout">
        <NavigationBar items={layoutData.navigation} />
        <main>{children}</main>
        <EditLink url={layoutData.editUrl} />
      </div>
    </LayoutContext.Provider>
  );
}

Via Compilation Step

Example

// mdx-loader-config.js import { compile } from '@mdx-js/mdx'; import remarkFrontmatter from 'remark-frontmatter'; import remarkMdxFrontmatter from 'remark-mdx-frontmatter'; const result = await compile(source, { remarkPlugins: [ remarkFrontmatter, [remarkMdxFrontmatter, { name: 'metadata' }], ], });

Common Layout Patterns

Documentation Layout

Example

export default function DocumentationLayout({ children, title, section, prev, next }) { return ( <div className="docs-layout grid grid-cols-[250px_1fr_200px] gap-6"> <nav className="docs-nav sticky top-0 h-screen overflow-y-auto p-4"> <DocsSidebar activeSection={section} /> </nav> <article className="docs-main py-8"> <h1>{title}</h1> {children} <PrevNextNavigation prev={prev} next={next} /> </article> <aside className="docs-toc sticky top-0 h-screen overflow-y-auto p-4"> <OnThisPage /> </aside> </div> ); }

Landing Page Layout

jsx example

export default function LandingLayout({ children, hero, cta }) {
  return (
    <div className="landing-layout">
      <NavBar transparent />
      {hero && <HeroSection {...hero} />}
      <div className="landing-content">{children}</div>
      {cta && <CTASection {...cta} />}
      <Footer variant="marketing" />
    </div>
  );
}

Performance Tips

Technique	Benefit
Memoize layout components	Prevents re-renders when only content changes
Use CSS Grid for layout structure	Hardware-accelerated, no JS layout shifts
Lazy load sidebar/TOC	Reduces initial bundle for mobile users
Static generation of layouts	Zero runtime layout computation

Best Practice: Keep layouts focused on structure, not content logic. Move data fetching to page-level getStaticProps or loaders, and pass results as props. This keeps layouts pure and reusable.

Layouts are the skeleton of any MDX-driven site. Get composition and conditional rendering right, and adding new page types becomes trivial.

Layouts wrap your MDX content in a consistent page structure. Think headers, footers, sidebars, nav — all applied automatically so you don't repeat yourself in every file.

How Layouts Work

A layout is just a React component. Your compiled MDX content gets passed in as children, and any frontmatter data comes along as props.

jsx example

// Basic layout concept
// Your MDX content becomes the children of the layout component
<Layout {...frontmatterProps}>
  <YourMDXContent />
</Layout>

That's it. Nothing magical.

Creating Layout Components

Basic Layout

jsx example

// layouts/BaseLayout.jsx
import React from 'react';
import Header from '../components/Header';
import Footer from '../components/Footer';
import SEO from '../components/SEO';

export default function BaseLayout({ children, title, description, author }) {
  return (
    <div className="base-layout">
      <SEO title={title} description={description} />
      <Header />
      <main className="content-wrapper">
        <article className="prose prose-lg max-w-4xl mx-auto py-8">
          {title && <h1 className="page-title">{title}</h1>}
          {author && (
            <p className="text-gray-600 text-sm">By {author}</p>
          )}
          {children}
        </article>
      </main>
      <Footer />
    </div>
  );
}

Using a Layout via Export

In your MDX file, set the layout with a default export:

Example

Using a Layout via Configuration

With frameworks like Next.js, you can set layouts globally instead of per-file:

Example

Nested Layouts

You can stack layouts. A base layout handles the global shell, while a docs layout adds a sidebar. They compose together.

jsx example

// layouts/DocsLayout.jsx
import React from 'react';
import BaseLayout from './BaseLayout';
import Sidebar from '../components/Sidebar';
import TableOfContents from '../components/TableOfContents';
import Breadcrumbs from '../components/Breadcrumbs';

export default function DocsLayout({ children, title, description, toc }) {
  return (
    <BaseLayout title={title} description={description}>
      <div className="docs-container flex gap-8">
        {/* Left Sidebar - Navigation */}
        <aside className="w-64 shrink-0 hidden lg:block">
          <Sidebar />
        </aside>

        {/* Main Content */}
        <div className="flex-1 min-w-0">
          <Breadcrumbs />
          <div className="docs-content">
            {children}
          </div>
        </div>

        {/* Right Sidebar - Table of Contents */}
        <aside className="w-56 shrink-0 hidden xl:block">
          <TableOfContents items={toc} />
        </aside>
      </div>
    </BaseLayout>
  );
}

Example

Layout Props and Frontmatter

Frontmatter data flows straight into your layout as props. You can control layout behavior from the MDX file itself:

mdx example

Your content here receives the layout specified in frontmatter...

Then you resolve which layout to use:

Example

Conditional Layouts Based on Frontmatter

You can pick layouts dynamically based on what's in the frontmatter:

Example

jsx example

// Conditional layout with feature flags
export default function SmartLayout({ children, ...props }) {
  const { sidebar = true, toc = true, fullWidth = false, theme } = props;

  return (
    <div className={`layout ${theme === 'dark' ? 'dark' : ''}`}>
      <div className={`flex ${fullWidth ? 'max-w-full' : 'max-w-7xl mx-auto'}`}>
        {sidebar && <Sidebar />}
        <main className="flex-1 px-6 py-8">
          {children}
        </main>
        {toc && <TableOfContents />}
      </div>
    </div>
  );
}

Layout Composition Patterns

Higher-Order Layout Pattern

A factory function that spits out configured layouts:

jsx example

// createLayout.js - Layout factory
export function createLayout(options = {}) {
  const {
    showHeader = true,
    showFooter = true,
    showSidebar = false,
    maxWidth = '4xl',
    padding = '8',
  } = options;

  return function ComposedLayout({ children, ...props }) {
    return (
      <div className="min-h-screen flex flex-col">
        {showHeader && <Header {...props} />}
        <div className="flex flex-1">
          {showSidebar && <Sidebar {...props} />}
          <main className={`flex-1 max-w-${maxWidth} mx-auto p-${padding}`}>
            {children}
          </main>
        </div>
        {showFooter && <Footer />}
      </div>
    );
  };
}

// Usage
const DocsLayout = createLayout({ showSidebar: true, maxWidth: '6xl' });
const BlogLayout = createLayout({ maxWidth: '3xl', padding: '12' });
const LandingLayout = createLayout({ showSidebar: false, showFooter: true, maxWidth: 'full' });

Slot-Based Layout Pattern

Let MDX pages inject content into specific regions:

Example

Passing Data to Layouts

Via Context Providers

jsx example

// layouts/DataLayout.jsx
import { createContext, useContext } from 'react';

const LayoutContext = createContext({});

export function useLayoutData() {
  return useContext(LayoutContext);
}

export default function DataLayout({ children, ...frontmatter }) {
  const layoutData = {
    ...frontmatter,
    breadcrumbs: generateBreadcrumbs(frontmatter.slug),
    navigation: getNavigation(frontmatter.section),
    editUrl: `https://github.com/repo/edit/main/docs/${frontmatter.slug}.mdx`,
  };

  return (
    <LayoutContext.Provider value={layoutData}>
      <div className="data-layout">
        <NavigationBar items={layoutData.navigation} />
        <main>{children}</main>
        <EditLink url={layoutData.editUrl} />
      </div>
    </LayoutContext.Provider>
  );
}

Via Compilation Step

Example

Common Layout Patterns

Documentation Layout

Example

Landing Page Layout

jsx example

export default function LandingLayout({ children, hero, cta }) {
  return (
    <div className="landing-layout">
      <NavBar transparent />
      {hero && <HeroSection {...hero} />}
      <div className="landing-content">{children}</div>
      {cta && <CTASection {...cta} />}
      <Footer variant="marketing" />
    </div>
  );
}

Performance Tips

Technique	Benefit
Memoize layout components	Prevents re-renders when only content changes
Use CSS Grid for layout structure	Hardware-accelerated, no JS layout shifts
Lazy load sidebar/TOC	Reduces initial bundle for mobile users
Static generation of layouts	Zero runtime layout computation

Best Practice: Keep layouts focused on structure, not content logic. Move data fetching to page-level getStaticProps or loaders, and pass results as props. This keeps layouts pure and reusable.

Layouts are the skeleton of any MDX-driven site. Get composition and conditional rendering right, and adding new page types becomes trivial.

MDX Layouts

How Layouts Work

Creating Layout Components

Basic Layout

Using a Layout via Export

Using a Layout via Configuration

Nested Layouts

Layout Props and Frontmatter

Conditional Layouts Based on Frontmatter

Layout Composition Patterns

Higher-Order Layout Pattern

Slot-Based Layout Pattern

Passing Data to Layouts

Via Context Providers

Via Compilation Step

Common Layout Patterns

Documentation Layout

Landing Page Layout

Performance Tips

Continue learning this concept

MDX Layouts

How Layouts Work

Creating Layout Components

Basic Layout

Using a Layout via Export

Using a Layout via Configuration

Nested Layouts

Layout Props and Frontmatter

Conditional Layouts Based on Frontmatter

Layout Composition Patterns

Higher-Order Layout Pattern

Slot-Based Layout Pattern

Passing Data to Layouts

Via Context Providers

Via Compilation Step

Common Layout Patterns

Documentation Layout

Landing Page Layout

Performance Tips

Continue learning this concept