mintlify__docs/zh/guides/custom-layouts.mdx

---
title: "构建自定义页面布局"
sidebarTitle: "自定义页面布局"
description: "使用页面模式和组件在 Mintlify 文档中构建自定义落地页、营销页面及其他非标准布局。"
keywords: ["landing page", "page mode", "custom mode", "frame mode", "hero section", "landing pages"]
---

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

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

<div id="choose-a-page-mode">
  ## 选择页面模式
</div>

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

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

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

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

<div id="build-a-landing-page">
  ## 构建落地页
</div>

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

<div id="set-up-the-page">
  ### 配置页面
</div>

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

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

<div id="create-a-hero-section">
  ### 创建 hero 区域
</div>

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

```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>
  同时包含浅色模式和深色模式的样式。使用带有 `dark:` 前缀的 Tailwind 类来处理深色模式。
</Tip>

<div id="add-navigation-cards">
  ### 添加导航卡片
</div>

使用 [Card](/zh/components/cards) 和 [Columns](/zh/components/columns) 组件在 hero 区域下方创建链接网格：

```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>
```

<div id="use-images-with-dark-mode-support">
  ### 使用支持深色模式的图片
</div>

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

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

<div id="use-react-components-for-interactive-layouts">
  ## 使用 React 组件构建交互式布局
</div>

对于可复用或交互式元素，直接在 MDX 文件中定义 [React 组件](/zh/customize/react-components)：

```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>
  避免在 HTML 元素上使用 `style` 属性。它可能导致页面加载时出现布局偏移。请改用 Tailwind CSS 类或[自定义 CSS 文件](/zh/customize/custom-scripts)。
</Warning>

<div id="add-custom-css">
  ## 添加自定义 CSS
</div>

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

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

然后在 MDX 中引用该类：

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

参阅[自定义脚本](/zh/customize/custom-scripts)了解更多关于自定义 CSS 和可用 CSS 选择器的信息。

<div id="full-example">
  ## 完整示例
</div>

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

````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>
````

<div id="tips">
  ## 提示
</div>

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