> ## Documentation Index
> Fetch the complete documentation index at: https://www.mintlify.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Build custom page layouts

> Use page modes and components to build custom landing pages, marketing pages, and other non-standard layouts in your Mintlify documentation.

Mintlify pages use a standard layout by default, with a sidebar, content area, and table of contents. Customize this layout with [page modes](/docs/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 | Best for |
| - | - | - | - | - |
| `default` | Yes | Yes | Yes | Standard documentation pages |
| `wide` | Yes | No | Yes | Pages without headings or needing extra width |
| `custom` | No | No | No | Landing pages, marketing pages, or full-canvas layouts |
| `frame` | Yes | No | Modified | Custom content that still needs sidebar navigation |
| `center` | No | No | Yes | Changelogs, focused reading experiences |

In `center` mode, the Maple and Almond themes keep their sidebar because it holds their navigation and search. The content centers in the remaining space.

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.

Custom mode pages have no default typography. Native HTML elements such as `<h2>` and `<p>` render with browser default styles, so style them explicitly with Tailwind CSS classes.

```yaml Example page frontmatter theme={null}
---
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 theme={null}
---
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 theme={null}
<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](/docs/components/cards) and [Columns](/docs/components/columns) components to create a grid of links below the hero section:

```mdx Example navigation cards theme={null}
<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 theme={null}
<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](/docs/customize/react-components) directly in your MDX file:

```mdx Example React component theme={null}
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](/docs/customize/custom-scripts) instead.
</Warning>

<Note>
  The web editor's live preview does not generate CSS for page-specific Tailwind classes, so custom layouts can look unstyled while you edit them. Check your styling with `mint dev`, a preview deployment, or a production deployment. See [Tailwind classes not applying in the editor's live preview](/docs/help-center/tailwind-classes-not-applying-in-editor-preview).
</Note>

## 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.

Use a custom CSS file when you need keyframe animations, complex selectors, or styles that apply across many pages. For one-off values, use a Tailwind [arbitrary value](/docs/customize/custom-scripts#arbitrary-values-and-variants) such as `w-[350px]` instead.

```css Example custom CSS file theme={null}
.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 theme={null}
<div className="landing-hero">
  <h1>Welcome to the docs</h1>
</div>
```

See [Custom scripts](/docs/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 theme={null}
---
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.
* **Style components directly.** Components accept a `className` prop, so you can adjust one instance without a wrapper element or a CSS override. See [Style components with className](/docs/customize/custom-scripts#style-components-with-classname).


## Related topics

- [Tailwind classes not applying in the editor's live preview](/docs/help-center/tailwind-classes-not-applying-in-editor-preview.md)
- [Pages](/docs/organize/pages.md)
- [Guides](/docs/guides/index.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.