MDX Layouts

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.