mintlify

$27

Search for existing content before creating new pages. You may need to update an existing page, add a section, or link to existing content rather than duplicating.

Read 2-3 similar pages to match the site's voice, structure, and formatting.

File format

Mintlify uses MDX files (.mdx or .md) with YAML frontmatter.

project/

├── docs.json           # Site configuration (required)

├── index.mdx

├── quickstart.mdx

├── guides/

│   └── example.mdx

├── openapi.yml         # API specification (optional)

├── images/             # Static assets

│   └── example.png

└── snippets/           # Reusable components

    └── component.jsx

File naming

• Match existing patterns in the directory

• If no existing files or mixed file naming patterns, use kebab-case: getting-started.mdx

• Add new pages to docs.json navigation or they won't appear in the sidebar

Internal links

• Use root-relative paths without file extensions: /getting-started/quickstart

• Do not use relative paths (../) or absolute URLs for internal pages

Images

Store images in an images/ directory. Reference with root-relative paths. All images require descriptive alt text.

![Dashboard showing analytics overview](/images/dashboard.png)

Page frontmatter

Every page requires title in its frontmatter. Include description and keywords for SEO.

---

title: "Clear, descriptive title"

description: "Concise summary for SEO and navigation."

keywords: ["relevant", "search", "terms"]

---

Common frontmatter fields

Field

Type

Required

Description

title

string

Yes

Page title in navigation and browser tabs.

description

string

No

Brief description for SEO. Displays under the title.

sidebarTitle

string

No

Short title for sidebar navigation.

icon

string

No

Lucide, Font Awesome, or Tabler icon name. Also accepts a URL or file path.

tag

string

No

Label next to page title in sidebar (e.g., "NEW").

hidden

boolean

No

Remove from sidebar. Page still accessible by URL.

mode

string

No

Page layout: default, wide, custom, frame, center.

keywords

array

No

Search terms for internal search and SEO.

api

string

No

API endpoint for interactive playground (e.g., "POST /users").

openapi

string

No

OpenAPI endpoint reference (e.g., "GET /endpoint").

Quick component reference

Below are the most commonly used components. For full props and all 24 components, read reference/components.md.

Callouts

<Note>Supplementary information, safe to skip.</Note>

<Info>Helpful context such as permissions or prerequisites.</Info>

<Tip>Recommendations or best practices.</Tip>

<Warning>Potentially destructive actions or important caveats.</Warning>

<Check>Success confirmation or completed status.</Check>

<Danger>Critical warnings about data loss or breaking changes.</Danger>

Steps

<Steps>

  <Step title="First step">

    Instructions for step one.

  </Step>

  <Step title="Second step">

    Instructions for step two.

  </Step>

</Steps>

Tabs and code groups

<Tabs>

  <Tab title="npm">

    ```bash

    npm install package-name

    ```

  </Tab>

  <Tab title="yarn">

    ```bash

    yarn add package-name

    ```

  </Tab>

</Tabs>

<CodeGroup>

const greeting = "Hello, world!";

greeting = "Hello, world!"

### Cards and columns

<Columns cols={2}>

<Card title="First card" icon="rocket" href="/quickstart">

Card description text.

</Card>

<Card title="Second card" icon="book" href="/guides">

Card description text.

</Card>

</Columns>

Use `<Columns>` to arrange cards (or other content) in a grid. `cols` accepts 1-4.

### Accordions

<AccordionGroup>

<Accordion title="First section">Content one.</Accordion>

<Accordion title="Second section">Content two.</Accordion>

</AccordionGroup>