TemperStack
Find Tools
Intermediate8 min readUpdated Mar 18, 2026

How to extend MDX with custom layouts on Shipixen

Quick Answer

Extend MDX with custom layouts on Shipixen by creating layout components in the components directory and configuring them in your MDX files using frontmatter. Shipixen automatically detects and applies custom layouts to your content pages.

Prerequisites

  1. Basic React/TypeScript knowledge
  2. Existing Shipixen project
  3. Familiarity with MDX syntax
  4. Understanding of Next.js layouts
1

Create a Custom Layout Component

Navigate to your Shipixen project and create a new file in components/layouts/CustomLayout.tsx. Define your layout component with props for children and frontMatter:

export default function CustomLayout({ children, frontMatter }) {
  return (
    <div className="custom-layout">
      <header>{frontMatter.title}</header>
      <main>{children}</main>
    </div>
  )
}
Tip
Use TypeScript interfaces to properly type your frontMatter props for better development experience.
2

Register Layout in MDX Configuration

Open next.config.js and add your custom layout to the MDX configuration. Import your layout and include it in the components object:

import CustomLayout from './components/layouts/CustomLayout'

const withMDX = require('@next/mdx')({
  options: {
    remarkPlugins: [],
    rehypePlugins: [],
  }
})

module.exports = withMDX({
  pageExtensions: ['js', 'jsx', 'mdx', 'md', 'ts', 'tsx']
})
Tip
Restart your development server after modifying next.config.js for changes to take effect.
3

Configure Layout Mapping

Create or update components/MDXComponents.tsx to map layout names to components. This allows you to specify layouts in MDX frontmatter:

import CustomLayout from './layouts/CustomLayout'
import DefaultLayout from './layouts/DefaultLayout'

const layoutComponents = {
  custom: CustomLayout,
  default: DefaultLayout
}

export default layoutComponents
Tip
Use descriptive layout names that clearly indicate their purpose and design.
4

Create Layout Wrapper Logic

In your pages/_app.tsx or create a new components/LayoutWrapper.tsx, add logic to dynamically select layouts based on frontmatter:

import layoutComponents from '../components/MDXComponents'

function LayoutWrapper({ children, frontMatter }) {
  const Layout = layoutComponents[frontMatter.layout] || layoutComponents.default
  return <Layout frontMatter={frontMatter}>{children}</Layout>
}
Tip
Always provide a fallback to a default layout to prevent rendering errors.
5

Update MDX Files with Layout Frontmatter

Add the layout property to your MDX files' frontmatter to specify which custom layout to use:

---
title: "My Custom Page"
layout: "custom"
description: "Page using custom layout"
---

# Your MDX Content Here

This page will use the CustomLayout component.
Tip
You can pass additional custom properties in frontmatter that your layout components can access.
6

Style Your Custom Layout

Add CSS styles to your custom layout either through CSS modules, styled-components, or Tailwind classes. Create styles/CustomLayout.module.css and import it in your layout component:

import styles from '../../styles/CustomLayout.module.css'

export default function CustomLayout({ children, frontMatter }) {
  return (
    <div className={styles.container}>
      <aside className={styles.sidebar}>Navigation</aside>
      <main className={styles.content}>{children}</main>
    </div>
  )
}
Tip
Use CSS Grid or Flexbox for responsive layout designs that work across all device sizes.
7

Test and Deploy Custom Layouts

Run npm run dev to test your custom layouts locally. Navigate to pages using your custom layout and verify they render correctly. Check responsive behavior and ensure all frontmatter data displays properly. Deploy using Shipixen's deployment options when satisfied with the results.
Tip
Test your layouts with different content lengths to ensure they handle edge cases gracefully.

Troubleshooting

Layout not applying to MDX pages
Verify the layout name in frontmatter matches exactly with the key in your layoutComponents object. Check for typos and case sensitivity.
Frontmatter data not available in layout
Ensure you're passing the frontMatter prop correctly through your LayoutWrapper and that your MDX processing configuration includes frontmatter parsing.
Styles not loading in custom layout
Check that CSS imports are correct and that your CSS modules or styled-components are properly configured in next.config.js.
Build errors with custom layouts
Verify all imports are correct, TypeScript types are properly defined, and that your layout components don't use client-side only features during SSR.

Related Guides

More Shipixen Tutorials

How to generate your first boilerplate

How to set up project locally

How to deploy to Vercel

How to add your first MDX blog post

Other Tool Tutorials

F

Framer Tutorials

G

Ghost Tutorials

S

Squarespace Tutorials

Ready to get started with Shipixen?

Put this tutorial into practice. Visit Shipixen and follow the steps above.

Visit Shipixen →