构建自定义页面布局

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

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

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

选择页面模式

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

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

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

自定义模式页面没有默认排版样式。诸如 <h2> 和 <p> 之类的原生 HTML 元素会以浏览器默认样式渲染，因此请使用 Tailwind CSS 类为它们显式设置样式。

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 文件。

Web 编辑器的实时预览不会为页面特有的 Tailwind 类生成 CSS，因此自定义布局在编辑时可能看起来没有样式。请通过 mint dev、预览部署或生产部署检查样式效果。参阅 Tailwind 类在编辑器实时预览中不生效。

添加自定义 CSS

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

当你需要关键帧动画、复杂选择器或应用于多个页面的样式时，请使用自定义 CSS 文件。对于一次性的值，请改用 Tailwind 任意值，例如 w-[350px]。

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。
直接为组件设置样式。 组件接受 className prop，因此你无需包裹元素或 CSS 覆盖即可调整单个实例。参阅使用 className 为组件设置样式。