构建自定义页面布局

使用页面模式和组件在 Mintlify 文档中构建自定义落地页、营销页面及其他非标准布局。

Mintlify 页面默认使用标准布局，包含侧边栏、内容区域和目录。你可以通过页面模式自定义此布局，以创建落地页、功能展示页或任何需要独特设计的页面。

本指南介绍如何使用页面模式、Tailwind CSS 和组件来构建自定义布局。

​

选择页面模式

在页面的 frontmatter 中设置 mode 字段，以控制显示哪些 UI 元素。

模式	侧边栏	目录	页脚	主题支持	适用场景
default	是	是	是	所有主题	标准文档页面
wide	是	否	是	所有主题	无标题的页面或需要更大宽度的页面
custom	否	否	否	所有主题	落地页、营销页面或全画布布局
frame	是	否	修改后	Aspen、Almond、Luma、Sequoia	需要侧边栏导航的自定义内容
center	否	否	是	Mint、Linden、Willow、Maple	更新日志、专注阅读体验

对于落地页，custom 模式为你提供最大的控制权。它移除除顶部导航栏外的所有 UI 元素，为你提供一块空白画布进行构建。

Example page frontmatter

---
title: "Welcome"
mode: "custom"
---

​

构建落地页

一个典型的落地页由 hero 区域、功能卡片和行动号召组合而成。

​

配置页面

创建一个使用 custom 模式的 MDX 文件：

Example landing page frontmatter

---
title: "Documentation"
description: "Everything you need to build with our platform."
mode: "custom"
---

​

创建 hero 区域

使用 HTML 和 Tailwind CSS 类来构建一个居中的 hero 区域：

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>

同时包含浅色模式和深色模式的样式。使用带有 dark: 前缀的 Tailwind 类来处理深色模式。

​

添加导航卡片

使用 Card 和 Columns 组件在 hero 区域下方创建链接网格：

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>

​

使用支持深色模式的图片

使用 Tailwind 的可见性类为浅色和深色模式显示不同的图片：

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"
/>

​

使用 React 组件构建交互式布局

对于可复用或交互式元素，直接在 MDX 文件中定义 React 组件：

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>

避免在 HTML 元素上使用 style 属性。它可能导致页面加载时出现布局偏移。请改用 Tailwind CSS 类或自定义 CSS 文件。

​

添加自定义 CSS

对于 Tailwind 未涵盖的样式，可向你的仓库中添加 CSS 文件。Mintlify 会在全站范围内应用 CSS 文件，使其类名在所有 MDX 文件中可用。

不支持 Tailwind CSS 的任意值（例如 w-[350px]）。对于 Tailwind 实用类未涵盖的值，请使用自定义 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%);
  }
}

然后在 MDX 中引用该类：

Example custom CSS usage

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

参阅自定义脚本了解更多关于自定义 CSS 和可用 CSS 选择器的信息。

​

完整示例

以下是一个完整的落地页示例，将 hero 区域与导航卡片相结合：

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>

​

提示

• 测试浅色和深色模式。 在两种模式下预览你的自定义布局，以发现遗漏的 dark: 样式。
• 使用 max-w-* 类来限制内容宽度，保持文本可读性。
• 确保响应式。 使用 Tailwind 的响应式前缀（sm:、md:、lg:）使你的布局在所有屏幕尺寸上都能正常显示。
• 组合使用模式。 对文档首页使用 custom 模式，其他页面使用 default 模式。模式按页面设置，因此不同页面可以使用不同的布局。
• 检查布局偏移。 如果元素在页面加载时发生跳动，请将内联 style 属性替换为 Tailwind 类或自定义 CSS。