From 8d11e6c79157bcba00c66ae2c405a2f59735e90a Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Sat, 21 Mar 2026 17:12:29 +0000 Subject: [PATCH 1/7] Add guide on custom page layouts and landing pages Generated-By: mintlify-agent --- docs.json | 1 + guides/custom-layouts.mdx | 234 ++++++++++++++++++++++++++++++++++++++ guides/index.mdx | 1 + 3 files changed, 236 insertions(+) create mode 100644 guides/custom-layouts.mdx diff --git a/docs.json b/docs.json index 0d53e0a0d..5091c0157 100644 --- a/docs.json +++ b/docs.json @@ -296,6 +296,7 @@ "guides/accessibility", "guides/content-types", "guides/content-templates", + "guides/custom-layouts", "guides/improving-docs", "guides/internationalization", "guides/linking", diff --git a/guides/custom-layouts.mdx b/guides/custom-layouts.mdx new file mode 100644 index 000000000..65ab7ee5a --- /dev/null +++ b/guides/custom-layouts.mdx @@ -0,0 +1,234 @@ +--- +title: "Build custom page layouts" +sidebarTitle: "Custom page layouts" +description: "Use page modes and components to create landing pages, marketing pages, and other custom layouts." +keywords: ["landing page", "custom layout", "page mode", "custom mode", "frame mode", "hero section", "landing pages"] +--- + +Mintlify pages use a standard layout by default, with a sidebar, content area, and table of contents. You can change this layout with [page modes](/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 without a separate frontend. + +## 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, full-canvas layouts | +| `frame` | Yes | No | No | Custom content that still needs sidebar navigation | +| `center` | No | No | Yes | Changelogs, focused reading experiences | + +For landing pages, `custom` mode gives you the most control. It removes all chrome except the top navbar, giving you a blank canvas. + +```yaml +--- +title: "Welcome" +mode: "custom" +--- +``` + + + Use `frame` mode when you want custom HTML content but still need sidebar navigation for context. + + +## Build a landing page + +A typical landing page combines a hero section, feature cards, and calls to action. Here's how to build one step by step. + +### Set up the page + +Create an MDX file with `custom` mode: + +```yaml +--- +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: + +```mdx +
+

+ Documentation +

+

+ Everything you need to build, deploy, and scale your application. +

+
+``` + + + Always include both light and dark mode styles. Use `dark:` prefixed Tailwind classes to handle dark mode. + + +### Add navigation cards + +Use the [Card](/components/cards) and [Columns](/components/columns) components to create a grid of links below the hero: + +```mdx +
+ + + Get up and running in under five minutes. + + + Explore endpoints, parameters, and examples. + + + Step-by-step tutorials for common tasks. + + + Reusable UI components for your docs. + + +
+``` + +### Use images with dark mode support + +Show different images for light and dark mode using Tailwind's visibility classes: + +```mdx +Platform overview showing the main dashboard. +Platform overview showing the main dashboard. +``` + +## Use React components for interactive layouts + +For reusable or interactive elements, define [React components](/customize/react-components) directly in your MDX file: + +```mdx +export const FeatureCard = ({ title, description, href }) => ( + +

+ {title} +

+

+ {description} +

+ +); + +
+ + +
+``` + + + Avoid using the `style` prop on elements in custom mode pages. It can cause a layout shift on page load. Use Tailwind CSS classes or a [custom CSS file](/customize/custom-scripts) instead. + + +## Add custom CSS + +For styles that Tailwind doesn't cover, create a CSS file in your repository. Mintlify automatically includes CSS files on every page. + +```css styles.css +.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 +
+

Welcome to the docs

+
+``` + +See [Custom scripts](/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 +--- +title: "Documentation" +description: "Everything you need to build with our platform." +mode: "custom" +--- + +export const HeroCard = ({ title, description, href, icon }) => ( + +

+ {title} +

+

+ {description} +

+ +); + +
+

+ Documentation +

+

+ Everything you need to build, deploy, and scale your application. +

+
+ +
+ + + + +
+```` + +## Tips + +- **Test both themes.** Always 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. diff --git a/guides/index.mdx b/guides/index.mdx index 42ebd184d..f214f3ed4 100644 --- a/guides/index.mdx +++ b/guides/index.mdx @@ -32,6 +32,7 @@ Make your documentation best in class. - [Accessibility](/guides/accessibility): Make your docs accessible to as many users as possible. - [Content types](/guides/content-types): Choose the right format for tutorials, how-tos, references, and explanations. - [Content templates](/guides/content-templates): Copy and modify templates for each content type. +- [Custom page layouts](/guides/custom-layouts): Use page modes and components to build landing pages and other custom layouts. - [Improve your docs](/guides/improving-docs): Use data and feedback to continuously improve your documentation. - [Internationalization](/guides/internationalization): Set up multi-language documentation to reach global audiences. - [Linking](/guides/linking): Create internal links, reference API endpoints, and maintain link integrity across your documentation. From 5613fb81e7dfdcd8f3db9ea338316e635c042204 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Sat, 21 Mar 2026 11:05:10 -0700 Subject: [PATCH 2/7] add theme support to table --- guides/custom-layouts.mdx | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/guides/custom-layouts.mdx b/guides/custom-layouts.mdx index 65ab7ee5a..611a01096 100644 --- a/guides/custom-layouts.mdx +++ b/guides/custom-layouts.mdx @@ -13,13 +13,13 @@ This guide covers how to use page modes, Tailwind CSS, and components to build c 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, full-canvas layouts | -| `frame` | Yes | No | No | Custom content that still needs sidebar navigation | -| `center` | No | No | Yes | Changelogs, focused reading experiences | +| 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, full-canvas layouts | +| `frame` | Yes | No | No | Aspen, Almond, Luma | Custom content that still needs sidebar navigation | +| `center` | No | No | Yes | Mint, Linden | Changelogs, focused reading experiences | For landing pages, `custom` mode gives you the most control. It removes all chrome except the top navbar, giving you a blank canvas. From 790eb56d3ce897a0fe02cc5cc899fe89bb6741b4 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Sat, 21 Mar 2026 11:05:32 -0700 Subject: [PATCH 3/7] more precise CSS language --- guides/custom-layouts.mdx | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/guides/custom-layouts.mdx b/guides/custom-layouts.mdx index 611a01096..0fc6a98b8 100644 --- a/guides/custom-layouts.mdx +++ b/guides/custom-layouts.mdx @@ -145,7 +145,11 @@ export const FeatureCard = ({ title, description, href }) => ( ## Add custom CSS -For styles that Tailwind doesn't cover, create a CSS file in your repository. Mintlify automatically includes CSS files on every page. +For styles that Tailwind doesn't cover, add a CSS file to your repository. Mintlify applies CSS files sitewide, 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. + ```css styles.css .landing-hero { From cbb2ebc93ba52632d2fb95c185c98f2f38d7b52f Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Sat, 21 Mar 2026 11:08:45 -0700 Subject: [PATCH 4/7] use Lucide icon name --- guides/custom-layouts.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/custom-layouts.mdx b/guides/custom-layouts.mdx index 0fc6a98b8..800494258 100644 --- a/guides/custom-layouts.mdx +++ b/guides/custom-layouts.mdx @@ -85,7 +85,7 @@ Use the [Card](/components/cards) and [Columns](/components/columns) components Step-by-step tutorials for common tasks. - + Reusable UI components for your docs. From 9c906b088dd502e76d96a9e6448900b3bac3b049 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Sat, 21 Mar 2026 11:18:08 -0700 Subject: [PATCH 5/7] copy edit --- guides/custom-layouts.mdx | 48 ++++++++++++++++++--------------------- 1 file changed, 22 insertions(+), 26 deletions(-) diff --git a/guides/custom-layouts.mdx b/guides/custom-layouts.mdx index 800494258..937ee175c 100644 --- a/guides/custom-layouts.mdx +++ b/guides/custom-layouts.mdx @@ -2,12 +2,12 @@ title: "Build custom page layouts" sidebarTitle: "Custom page layouts" description: "Use page modes and components to create landing pages, marketing pages, and other custom layouts." -keywords: ["landing page", "custom layout", "page mode", "custom mode", "frame mode", "hero section", "landing pages"] +keywords: ["landing page", "page mode", "custom mode", "frame mode", "hero section", "landing pages"] --- -Mintlify pages use a standard layout by default, with a sidebar, content area, and table of contents. You can change this layout with [page modes](/organize/pages#page-mode) to create landing pages, feature showcases, or any page that needs a unique design. +Mintlify pages use a standard layout by default, with a sidebar, content area, and table of contents. Customize this layout with [page modes](/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 without a separate frontend. +This guide covers how to use page modes, Tailwind CSS, and components to build custom layouts. ## Choose a page mode @@ -17,32 +17,28 @@ Set the `mode` field in your page's frontmatter to control which UI elements app |------|---------|-------------------|--------|---------------|----------| | `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, full-canvas layouts | +| `custom` | No | No | No | All themes | Landing pages, marketing pages, or full-canvas layouts | | `frame` | Yes | No | No | Aspen, Almond, Luma | Custom content that still needs sidebar navigation | | `center` | No | No | Yes | Mint, Linden | Changelogs, focused reading experiences | -For landing pages, `custom` mode gives you the most control. It removes all chrome except the top navbar, giving you a blank canvas. +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. -```yaml +```yaml Example page frontmatter --- title: "Welcome" mode: "custom" --- ``` - - Use `frame` mode when you want custom HTML content but still need sidebar navigation for context. - - ## Build a landing page -A typical landing page combines a hero section, feature cards, and calls to action. Here's how to build one step by step. +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 +```yaml Example landing page frontmatter --- title: "Documentation" description: "Everything you need to build with our platform." @@ -52,9 +48,9 @@ mode: "custom" ### Create a hero section -Use HTML with Tailwind CSS classes to build a centered hero: +Use HTML with Tailwind CSS classes to build a centered hero section: -```mdx +```mdx Example hero section

Documentation @@ -65,15 +61,15 @@ Use HTML with Tailwind CSS classes to build a centered hero:

``` - - Always include both light and dark mode styles. Use `dark:` prefixed Tailwind classes to handle dark mode. - + + Include both light and dark mode styles. Use `dark:` prefixed Tailwind classes to handle dark mode. + ### Add navigation cards -Use the [Card](/components/cards) and [Columns](/components/columns) components to create a grid of links below the hero: +Use the [Card](/components/cards) and [Columns](/components/columns) components to create a grid of links below the hero section: -```mdx +```mdx Example navigation cards
@@ -96,7 +92,7 @@ Use the [Card](/components/cards) and [Columns](/components/columns) components Show different images for light and dark mode using Tailwind's visibility classes: -```mdx +```mdx Example images with dark mode support Platform overview showing the main dashboard. (

@@ -151,7 +147,7 @@ For styles that Tailwind doesn't cover, add a CSS file to your repository. Mintl 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. -```css styles.css +```css Example custom CSS file .landing-hero { background: linear-gradient(135deg, #f0f9ff 0%, #e0f2fe 100%); padding: 4rem 2rem; @@ -166,7 +162,7 @@ For styles that Tailwind doesn't cover, add a CSS file to your repository. Mintl Then reference the class in your MDX: -```mdx +```mdx Example custom CSS usage

Welcome to the docs

@@ -178,7 +174,7 @@ See [Custom scripts](/customize/custom-scripts) for more on custom CSS and the a Here's a complete landing page that combines a hero section with navigation cards: -````mdx +````mdx Example landing page --- title: "Documentation" description: "Everything you need to build with our platform." @@ -208,7 +204,7 @@ export const HeroCard = ({ title, description, href, icon }) => (
( ## Tips -- **Test both themes.** Always preview your custom layout in both light and dark mode to catch missing `dark:` styles. +- **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. From 54d3d5212b6f2f2f2d48767a041b042cdbd30629 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Sat, 21 Mar 2026 11:31:55 -0700 Subject: [PATCH 6/7] accuracy --- guides/custom-layouts.mdx | 6 +++--- organize/pages.mdx | 6 +++--- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/guides/custom-layouts.mdx b/guides/custom-layouts.mdx index 937ee175c..77ef47049 100644 --- a/guides/custom-layouts.mdx +++ b/guides/custom-layouts.mdx @@ -18,8 +18,8 @@ Set the `mode` field in your page's frontmatter to control which UI elements app | `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 | No | Aspen, Almond, Luma | Custom content that still needs sidebar navigation | -| `center` | No | No | Yes | Mint, Linden | Changelogs, focused reading experiences | +| `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. @@ -136,7 +136,7 @@ export const FeatureCard = ({ title, description, href }) => ( ``` - Avoid using the `style` prop on elements in custom mode pages. It can cause a layout shift on page load. Use Tailwind CSS classes or a [custom CSS file](/customize/custom-scripts) instead. + 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](/customize/custom-scripts) instead. ## Add custom CSS diff --git a/organize/pages.mdx b/organize/pages.mdx index 226094016..719638520 100644 --- a/organize/pages.mdx +++ b/organize/pages.mdx @@ -120,12 +120,12 @@ mode: "custom" ``` - The `style` property on custom mode pages may cause a layout shift on page load. Prefer [Tailwind CSS or custom CSS](/customize/custom-scripts) to avoid this issue. + The `style` property may cause a layout shift on page load. Prefer [Tailwind CSS or custom CSS](/customize/custom-scripts) to avoid this issue. ### Frame -Frame mode provides a layout similar to custom mode but keeps the sidebar navigation. Use this mode to include custom HTML and components while preserving the default navigation experience. Only Aspen, Almond, and Luma themes support frame mode. +Frame mode provides a layout similar to custom mode but keeps the sidebar navigation. Use this mode to include custom HTML and components while preserving the default navigation experience. Aspen, Almond, Luma, and Sequoia themes support frame mode. ```yaml --- @@ -136,7 +136,7 @@ mode: "frame" ### Center -Center mode removes the sidebar and table of contents, and centers the content. Use center mode for changelogs or other pages where you want to place focus on the content. Mint and Linden themes support center mode. +Center mode removes the sidebar and table of contents, and centers the content. Use center mode for changelogs or other pages where you want to place focus on the content. Mint, Linden, Willow, and Maple themes support center mode. ```yaml --- From 405b2ed8cac7a3c56420a6c04aaa19203ce6ab9e Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Sat, 21 Mar 2026 11:33:19 -0700 Subject: [PATCH 7/7] Apply suggestion from @ethanpalm --- guides/custom-layouts.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/custom-layouts.mdx b/guides/custom-layouts.mdx index 77ef47049..119c12ba1 100644 --- a/guides/custom-layouts.mdx +++ b/guides/custom-layouts.mdx @@ -141,7 +141,7 @@ export const FeatureCard = ({ title, description, href }) => ( ## Add custom CSS -For styles that Tailwind doesn't cover, add a CSS file to your repository. Mintlify applies CSS files sitewide, making their class names available in all MDX files. +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. 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.