Build custom page layouts

Docfiy pages use a standard layout by default, with a sidebar, content area, and table of contents. Customize this layout with page modes 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.

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:

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:

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>

Include both light and dark mode styles. Use dark: prefixed Tailwind classes to handle dark mode.

Use the Card and Columns components to create a grid of links below the hero section:

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:

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 directly in your MDX file:

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>

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

Add custom CSS

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

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.

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:

Example custom CSS usage

<div className="landing-hero">
  <h1>Welcome to the docs</h1>
</div>

See 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:

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.

Choose a page mode

Build a landing page

Set up the page

Create a hero section

Add navigation cards

Use images with dark mode support

Use React components for interactive layouts

Add custom CSS

Full example

Tips