mintlify__docs/guides/custom-layouts.mdx

---
title: "Build custom page layouts"
sidebarTitle: "Custom page layouts"
description: "Use page modes and components to build custom landing pages, marketing pages, and other non-standard layouts in your Mintlify documentation."
keywords: ["landing page", "page mode", "custom mode", "frame mode", "hero section", "landing pages"]
---

Mintlify pages use a standard layout by default, with a sidebar, content area, and table of contents. Customize this layout with [page modes](/organize/pages#page-mode) to create landing pages, feature showcases, or any page that needs a unique design.

This guide covers how to use page modes, Tailwind CSS, and components to build custom layouts.

## Choose a page mode

Set the `mode` field in your page's frontmatter to control which UI elements appear.

| Mode | Sidebar | Table of contents | Footer | Theme support | Best for |
|------|---------|-------------------|--------|---------------|----------|
| `default` | Yes | Yes | Yes | All themes | Standard documentation pages |
| `wide` | Yes | No | Yes | All themes | Pages without headings or needing extra width |
| `custom` | No | No | No | All themes | Landing pages, marketing pages, or full-canvas layouts |
| `frame` | Yes | No | Modified | Aspen, Almond, Luma, Sequoia | Custom content that still needs sidebar navigation |
| `center` | No | No | Yes | Mint, Linden, Willow, Maple | Changelogs, focused reading experiences |

For landing pages, `custom` mode gives you the most control. It removes all UI elements except the top navbar, giving you a blank canvas to build on.

```yaml Example page frontmatter
---
title: "Welcome"
mode: "custom"
---
```

## Build a landing page

A typical landing page combines a hero section, feature cards, and calls to action.

### Set up the page

Create an MDX file with `custom` mode:

```yaml Example landing page frontmatter
---
title: "Documentation"
description: "Everything you need to build with our platform."
mode: "custom"
---
```

### Create a hero section

Use HTML with Tailwind CSS classes to build a centered hero section:

```mdx Example hero section
<div className="px-4 py-16 lg:py-32 max-w-3xl mx-auto text-center">
  <h1 className="text-4xl font-medium text-gray-900 dark:text-zinc-50 tracking-tight">
    Documentation
  </h1>
  <p className="mt-4 text-lg text-gray-500 dark:text-zinc-500">
    Everything you need to build, deploy, and scale your application.
  </p>
</div>
```

<Tip>
  Include both light and dark mode styles. Use `dark:` prefixed Tailwind classes to handle dark mode.
</Tip>

### Add navigation cards

Use the [Card](/components/cards) and [Columns](/components/columns) components to create a grid of links below the hero section:

```mdx Example navigation cards
<div className="max-w-4xl mx-auto px-6">
  <Columns cols={2}>
    <Card title="Quickstart" icon="rocket" href="/quickstart">
      Get up and running in under five minutes.
    </Card>
    <Card title="API reference" icon="code" href="/api-reference">
      Explore endpoints, parameters, and examples.
    </Card>
    <Card title="Guides" icon="book" href="/guides">
      Step-by-step tutorials for common tasks.
    </Card>
    <Card title="Components" icon="puzzle" href="/components">
      Reusable UI components for your docs.
    </Card>
  </Columns>
</div>
```

### Use images with dark mode support

Show different images for light and dark mode using Tailwind's visibility classes:

```mdx Example images with dark mode support
<img
  src="/images/hero-light.png"
  alt="Platform overview showing the main dashboard."
  className="block dark:hidden"
/>
<img
  src="/images/hero-dark.png"
  alt="Platform overview showing the main dashboard."
  className="hidden dark:block"
/>
```

## Use React components for interactive layouts

For reusable or interactive elements, define [React components](/customize/react-components) directly in your MDX file:

```mdx Example React component
export const FeatureCard = ({ title, description, href }) => (
  <a className="group block p-6 rounded-xl border border-gray-200 dark:border-zinc-800 hover:border-gray-300 dark:hover:border-zinc-700 transition-colors" href={href}>
    <h3 className="font-medium text-gray-900 dark:text-zinc-50 group-hover:underline">
      {title}
    </h3>
    <p className="mt-2 text-sm text-gray-500 dark:text-zinc-500">
      {description}
    </p>
  </a>
);

<div className="max-w-4xl mx-auto px-6 grid sm:grid-cols-2 gap-4">
  <FeatureCard
    title="Authentication"
    description="Set up OAuth, API keys, and session management."
    href="/guides/authentication"
  />
  <FeatureCard
    title="Webhooks"
    description="Receive real-time notifications for events."
    href="/guides/webhooks"
  />
</div>
```

<Warning>
  Avoid using the `style` prop on HTML elements. It can cause a layout shift on page load. Use Tailwind CSS classes or a [custom CSS file](/customize/custom-scripts) instead.
</Warning>

## Add custom CSS

For styles that Tailwind doesn't cover, add a CSS file to your repository. Mintlify applies CSS files site-wide, making their class names available in all MDX files.

<Note>
  Tailwind CSS arbitrary values (for example, `w-[350px]`) are not supported. Use a custom CSS file for values that Tailwind's utility classes don't cover.
</Note>

```css Example custom CSS file
.landing-hero {
  background: linear-gradient(135deg, #f0f9ff 0%, #e0f2fe 100%);
  padding: 4rem 2rem;
}

@media (prefers-color-scheme: dark) {
  .landing-hero {
    background: linear-gradient(135deg, #0c1222 0%, #1a1a2e 100%);
  }
}
```

Then reference the class in your MDX:

```mdx Example custom CSS usage
<div className="landing-hero">
  <h1>Welcome to the docs</h1>
</div>
```

See [Custom scripts](/customize/custom-scripts) for more on custom CSS and the available CSS selectors.

## Full example

Here's a complete landing page that combines a hero section with navigation cards:

````mdx Example landing page
---
title: "Documentation"
description: "Everything you need to build with our platform."
mode: "custom"
---

export const HeroCard = ({ title, description, href, icon }) => (
  <a className="group block p-6 rounded-xl border border-gray-200 dark:border-zinc-800 hover:border-gray-300 dark:hover:border-zinc-700 transition-colors" href={href}>
    <h3 className="font-medium text-gray-900 dark:text-zinc-50">
      {title}
    </h3>
    <p className="mt-2 text-sm text-gray-500 dark:text-zinc-500">
      {description}
    </p>
  </a>
);

<div className="px-4 py-16 lg:py-32 max-w-3xl mx-auto text-center">
  <h1 className="text-4xl font-medium text-gray-900 dark:text-zinc-50 tracking-tight">
    Documentation
  </h1>
  <p className="mt-4 text-lg text-gray-500 dark:text-zinc-500 max-w-xl mx-auto">
    Everything you need to build, deploy, and scale your application.
  </p>
</div>

<div className="max-w-4xl mx-auto px-6 pb-16 grid sm:grid-cols-2 gap-4">
  <HeroCard
    title="Quickstart"
    description="Get up and running."
    href="/quickstart"
  />
  <HeroCard
    title="API reference"
    description="Explore endpoints, parameters, and examples."
    href="/api-reference"
  />
  <HeroCard
    title="Guides"
    description="Step-by-step tutorials for common tasks."
    href="/guides"
  />
  <HeroCard
    title="SDKs"
    description="Client libraries for every major language."
    href="/sdks"
  />
</div>
````

## Tips

- **Test light and dark mode.** Preview your custom layout in both light and dark mode to catch missing `dark:` styles.
- **Use `max-w-*` classes** to constrain content width and keep text readable.
- **Keep it responsive.** Use Tailwind's responsive prefixes (`sm:`, `md:`, `lg:`) so your layout works on all screen sizes.
- **Combine modes.** Use `custom` mode for your docs home page and `default` mode for everything else. You set the mode per page, so different pages can use different layouts.
- **Check for layout shifts.** If elements jump on page load, replace inline `style` props with Tailwind classes or custom CSS.