Key concepts

Projects, pages, navigation, and components — the building blocks of a Mintlify docs site.

Understanding these four concepts makes every other guide easier to follow.

Projects

A project is a docs site. Each project is backed by a Git repository and gets its own URL (a subdomain on mintlify.app until you configure a custom domain). Settings, collaborators, and deployments are all scoped to the project.

Projects deploy automatically every time you push to your default branch. Pull requests get preview deployments at unique URLs so you can review changes before they go live.

Pages

Every page on your site corresponds to one MDX file in your repository. The file path determines the URL: platform/quickstart.mdx becomes /platform/quickstart.

Pages start with a frontmatter block:

---
title: "My page title"
description: "Shown in search results and link previews."
---

Page content goes here.

Beyond standard Markdown, MDX lets you embed components directly in your content.

Navigation

Your sidebar structure is defined in docs.json under the navigation key. The three main building blocks are:

Element	What it does
Groups	Collapsible sections in the sidebar that contain pages or nested groups.
Tabs	A horizontal bar at the top of the sidebar for switching between major sections.
Anchors	Persistent sidebar links to external URLs or specific pages, always visible regardless of which page is open.

You can also use Products to separate entirely different documentation sets (for example, a public API reference and an internal admin guide) behind a product switcher.

Components

Mintlify ships a library of MDX components you can use on any page without any imports:

Cards

Highlight links, features, or resources in a visual grid.

Steps

Numbered, visually separated step sequences for procedures.

Tabs

Switch between multiple views of related content on a single page.

Callouts

Note, Tip, Warning, and Danger blocks for important information.

Code

Syntax-highlighted blocks with copy buttons and multi-language tab groups.

API Playground

Interactive request builder generated automatically from your OpenAPI spec.

Themes

Mintlify’s themes control your site’s overall look. Set "theme" in docs.json to one of the built-in options (mint, willow, almond, sequoia, and more). Every theme supports light and dark mode and can be customized with your brand colors, fonts, and custom CSS.