Pages

Configure page metadata, titles, and frontmatter properties.

Each page is a Markdown file. You can use either .mdx or .md file types for your pages. We recommend MDX, which combines Markdown with React components for rich, interactive documentation. Plain Markdown (.md) can expedite migration from other platforms, but switching to MDX enables more features.

Page metadata

Every page begins with frontmatter, the YAML metadata enclosed by --- at the top of a file. This metadata controls how your page appears and behaves.

Use frontmatter to control:

• Page titles and descriptions
• Sidebar titles, icons, and tags
• Page layouts
• SEO meta tags
• Custom metadata

title · string · required

The title of your page that appears in navigation and browser tabs.

description · string

A brief description of what this page covers. Displays under the title and improves SEO.

sidebarTitle · string

A short title that displays in the sidebar navigation.

icon · string

The icon to display.

Options:

• Font Awesome icon name
• Lucide icon name
• Tabler icon name
• URL to an externally hosted icon
• Path to an icon file in your project

iconType · string

For Font Awesome icons only. The style of the icon.

Options: regular, solid, light, thin, sharp-solid, duotone, brands.

tag · string

A tag that appears next to your page title in the sidebar.

hidden · boolean

Set to true to remove the page from the sidebar navigation. Users can still access the page via its URL, but search engines do not index it. See Hidden pages for details.

noindex · boolean

Set to true to prevent search engines from indexing the page. See Disable indexing for details. All pages with hidden: true in their frontmatter receive noindex: true automatically.

<custom> · string

Any valid YAML frontmatter. For example, product: "API" or version: "1.0.0".

Example YAML frontmatter

---
title: "About frontmatter"
description: "Frontmatter is the metadata that controls how your page appears and behaves"
sidebarTitle: "Frontmatter"
icon: "book"
tag: "NEW"
---

Tags and labels

Tags are visual indicators that appear next to page titles and navigation groups in your sidebar. Use tags to highlight the status or importance of content, such as new features, beta functionality, or deprecated endpoints.

Tag vs label

Mintlify uses the term tag consistently across both page frontmatter and navigation configuration. There is no separate “label” concept—tags serve as the universal labeling mechanism throughout your documentation.

• Page-level tags: Defined in page frontmatter using the tag property
• Group-level tags: Defined in navigation groups using the tag property

Both types of tags appear as small badges in the sidebar navigation, helping users quickly identify the status or category of content.

Where tags appear

Tags display in the following locations:

• Sidebar navigation: Next to page titles and group names
• Search results: Tags from page frontmatter appear alongside search results
• Navigation hierarchy: Tags inherit visual styling from your theme

Tags do not appear in page content, browser tabs, or SEO meta tags—they are purely navigational indicators.

Using tags in page frontmatter

Add a tag to any page by including the tag property in your frontmatter:

---
title: "Webhooks API"
tag: "BETA"
---

The tag appears next to the page title in the sidebar navigation. You can use any string value for tags, but keep them short (typically 3-8 characters) for optimal display.

Using tags in navigation groups

Add tags to navigation groups in your docs.json to label entire sections:

{
  "navigation": {
    "groups": [
      {
        "group": "Experimental features",
        "tag": "BETA",
        "pages": ["experimental/feature-a", "experimental/feature-b"]
      }
    ]
  }
}

Group tags appear next to the group name in the sidebar, indicating that all pages within the group share that status.

Common tag use cases

Use tags to communicate content status and guide user expectations:

NEW - Recently added features

Highlight new features, endpoints, or documentation sections that users should explore.

---
title: "Real-time notifications"
tag: "NEW"
---

BETA - Pre-release functionality

Mark features that are available but still under active development or testing.

---
title: "GraphQL API"
tag: "BETA"
---

DEPRECATED - Legacy content

Warn users about features or endpoints that will be removed in future versions.

---
title: "Legacy authentication"
tag: "DEPRECATED"
---

PREVIEW - Early access features

Indicate features available to select users or requiring special access.

---
title: "AI-powered search"
tag: "PREVIEW"
---

ENTERPRISE - Paid tier features

Distinguish features available only to enterprise or premium customers.

---
title: "Advanced analytics"
tag: "ENTERPRISE"
---

Custom metadata properties

Beyond standard frontmatter fields, you can add custom metadata properties to organize and categorize your documentation:

---
title: "User authentication"
description: "Learn how to authenticate users"
product: "API"
version: "2.0"
audience: "developers"
difficulty: "intermediate"
---

Custom metadata properties:

• Are valid YAML: Any valid YAML key-value pair works
• Do not appear in the UI: Custom properties are not displayed to users by default
• Cannot be queried or filtered: Mintlify does not provide built-in search or filtering for custom metadata
• Serve as documentation: Use them to organize content internally or for future tooling

Custom metadata is useful for internal organization, documentation workflows, or integration with external tools that process your MDX files.

Page-level vs global metadata

Understanding when to use page frontmatter versus global configuration in docs.json helps you maintain consistent, scalable documentation.

Page-level metadata (frontmatter)

Use frontmatter for properties that vary between individual pages:

---
title: "Getting started with webhooks"
description: "Set up webhook endpoints to receive real-time events"
icon: "webhook"
tag: "NEW"
---

Best for:

• Page-specific titles, descriptions, and icons
• Individual page tags and status indicators
• Page-specific SEO metadata
• Custom metadata unique to each page
• Page layout modes (wide, custom, frame)

Global metadata (docs.json)

Use docs.json for properties that apply across multiple pages or define site-wide behavior:

{
  "name": "Acme API Documentation",
  "logo": "/logo.png",
  "metadata": {
    "og:image": "/social-preview.jpg",
    "twitter:site": "@acmeapi"
  },
  "navigation": {
    "groups": [
      {
        "group": "API Reference",
        "tag": "STABLE",
        "pages": ["api/users", "api/orders"]
      }
    ]
  }
}

Best for:

• Site-wide branding (name, logo, favicon)
• Default SEO metadata for all pages
• Navigation structure and hierarchy
• Group-level tags that apply to multiple pages
• Theme and styling configuration
• Global features (analytics, search, feedback)

When to use each

Scenario	Use frontmatter	Use docs.json
Set a page title	✓
Add a tag to one page	✓
Add a tag to a group of pages		✓
Configure site-wide SEO		✓
Override SEO for one page	✓
Organize navigation structure		✓
Set page-specific icon	✓
Set group-level icon		✓

Example: Combining both approaches

Page frontmatter (api/webhooks.mdx)

---
title: "Webhooks"
description: "Receive real-time event notifications"
tag: "BETA"
icon: "webhook"
---

Global configuration (docs.json)

{
  "navigation": {
    "groups": [
      {
        "group": "API Reference",
        "tag": "STABLE",
        "icon": "square-terminal",
        "pages": [
          "api/authentication",
          "api/users",
          "api/webhooks"
        ]
      }
    ]
  }
}

In this example, the “Webhooks” page displays both its page-level tag (“BETA”) and inherits the group structure from docs.json. The page-level tag takes precedence for that specific page, while other pages in the group would display the group-level tag if they don’t have their own.

Page mode

Control your page’s layout with the mode setting.

Default

If you do not define a mode, the page uses a standard layout with sidebar navigation and table of contents.

---
title: "Default page title"
---

Wide

Wide mode hides the table of contents. Use this mode for pages without headings or if you want extra horizontal space. Every theme supports wide mode.

---
title: "Wide page title"
mode: "wide"
---

Custom

Custom mode provides a minimalist layout and removes all elements except for the top navbar. Treat custom mode as a blank canvas to build landing pages or unique layouts with minimal navigation. All themes support custom mode.

---
title: "Custom page title"
mode: "custom"
---

The style property on custom mode pages may cause a layout shift on page load. Prefer Tailwind CSS or custom CSS 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.

---
title: "Frame page title"
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.

---
title: "Center page title"
mode: "center"
---

API pages

To create an interactive API playground, add an API specification to your frontmatter by setting api or openapi.

---
openapi: "GET /endpoint"
---

Learn more about building API documentation.

External links

Link to external sites directly from your navigation with the url metadata.

---
title: "npm Package"
url: "https://www.npmjs.com/package/mint"
---

Search engine optimization

Mintlify automatically generates most SEO meta tags. You can set SEO meta tags manually to customize your approach to SEO, social sharing, and browser compatibility.

Always wrap meta tags with colons in quotes.

---
"twitter:image": "/images/social-preview.jpg"
---

See SEO for the full list of SEO metadata options.

Internal search keywords

Help users discover a specific page in search results by providing keywords in your metadata. These keywords don’t appear in page content. If users search for the keywords, the page appears in the search results.

---
keywords: ['configuration', 'setup', 'getting started']
---

Last modified timestamp

Show a “Last modified on [date]” timestamp on all pages by enabling metadata.timestamp in your global settings.

docs.json

"metadata": {
  "timestamp": true
}

To override the global timestamp setting for an individual page, use the timestamp frontmatter field. Use this field to show or hide timestamps on specific pages.

---
title: "Page title"
timestamp: false
---

If you set timestamp: true, the page always shows the timestamp even if the global setting is false. If you set timestamp: false, the page hides the timestamp even if the global setting is true.