mintlify

Mintlify

Overview

Mintlify builds a documentation site from a Git repository of .mdx pages plus one configuration file, docs.json. The CLI is the npm package mint (the old mintlify package is legacy: do not install it). Pushing to the connected branch deploys the site to https://<subdomain>.mintlify.site, and a custom domain can be added. Search, the AI assistant, analytics and the API playground are part of the hosted platform; the local preview shows the pages, and search needs mint login.

The configuration file used to be mint.json. Current projects use docs.json. If you find a mint.json, convert it to docs.json by hand against the docs.json schema ("$schema": "https://mintlify.com/docs.json" gives editor validation, and mint validate reports mistakes) instead of extending it.

Instructions

1. Install the CLI and scaffold a project

node --version                      # needs v20.17.0 or newer
npm i -g mint
mint new acme-docs --name "Acme Billing" --theme mint     # non-interactive; scaffolds into acme-docs/
cd acme-docs
mint dev                            # preview on http://localhost:3000; add --port 3459 to change it

mint dev serves on localhost only unless you pass --host. Never use mint new --force in a folder with files you want to keep. Other commands: mint validate (strict build check, fails on warnings), mint broken-links, mint a11y, mint format, mint update, mint status.

2. Configure docs.json

This configuration was validated with mint validate (CLI 4.2.x). Pages are listed by path without extension.

{
  "$schema": "https://mintlify.com/docs.json",
  "theme": "mint",
  "name": "Acme Billing",
  "colors": { "primary": "#0D9373", "light": "#07C983", "dark": "#0D9373" },
  "favicon": "/favicon.svg",
  "logo": { "light": "/logo/light.svg", "dark": "/logo/dark.svg" },
  "navigation": {
    "tabs": [
      {
        "tab": "Guides",
        "groups": [
          { "group": "Getting started", "pages": ["index", "quickstart"] },
          { "group": "Guides", "pages": ["guides/webhooks"] }
        ]
      },
      {
        "tab": "API reference",
        "groups": [
          { "group": "Overview", "pages": ["api-reference/introduction"] },
          { "group": "Invoices", "openapi": "api-reference/openapi.json" }
        ]
      }
    ]
  },
  "navbar": {
    "links": [{ "label": "Status", "href": "https://status.acme-billing.io" }],
    "primary": { "type": "button", "label": "Dashboard", "href": "https://app.acme-billing.io" }
  },
  "footer": { "socials": { "github": "https://github.com/mintlify" } }
}

logo.href and the href of navbar links and buttons accept absolute URLs or paths that start with /; an outdated CLI rejects relative paths with Must be a valid url, so run mint update.

3. Write pages in MDX

Each page starts with title and description frontmatter. Built-in components include <Note>, <Warning>, <Tip>, <Steps>/<Step>, <CodeGroup>, <Card>, <ParamField> and <ResponseExample>.

---
title: "Webhooks"
description: "Receive invoice events"
---

<Steps>
  <Step title="Add an endpoint">Register `https://shop.acme-billing.io/hooks` in the dashboard.</Step>
  <Step title="Verify the signature">Reject requests whose signature does not match.</Step>
</Steps>

<CodeGroup>

npm install @acme-billing/sdk

pnpm add @acme-billing/sdk

</CodeGroup>

<Card title="API reference" icon="code" href="/api-reference/introduction">Explore endpoints</Card>

4. API reference

Preferred: put an OpenAPI 3 file in the repo and reference it from navigation with "openapi": "api-reference/openapi.json" (every endpoint becomes a page with a playground), or list endpoints ("GET /v1/invoices") under pages to choose some. Check the spec with mint validate. The playground uses the spec's servers and security.

For a small API, write endpoint pages by hand. Configure the server and auth once, then give each page an api frontmatter field (a relative path needs the server value):

{ "api": { "mdx": { "server": "https://api.acme-billing.io/", "auth": { "method": "bearer" } } } }

---
title: "Create invoice"
api: "POST /v1/invoices"
---

<ParamField body="customer_id" type="string" required>Customer to bill</ParamField>
<ParamField body="amount" type="integer" required>Amount in cents</ParamField>

5. Deploy

mint login (existing account) or mint signup, connect the GitHub repository in the browser, then push to the production branch. mint status shows the subdomain. Run mint validate and mint broken-links before every push (they work offline).

Examples

Example 1: Document a REST API from its OpenAPI spec

Request: "Generate documentation for our billing API from openapi.yaml."

Run mint new billing-docs --name "Acme Billing" --theme mint, copy the spec to billing-docs/api-reference/openapi.yaml, add a group with "openapi": "api-reference/openapi.yaml" to the navigation, run mint validate, then mint dev --port 3459. Result: validation prints success build validation passed and the preview has one page per endpoint with a request playground.

Example 2: Product docs with a quickstart and guides

Request: "Set up docs for our SaaS: quickstart, two guides and an API reference tab."

Scaffold with mint new, write quickstart.mdx and guides/*.mdx using <Steps> and <CodeGroup>, define two tabs in docs.json as in step 2, and run mint broken-links. Result: success no broken links found, with Guides and API reference tabs in the top navigation.

Guidelines

• Treat docs.json as the source of truth for navigation: a page that exists as a file but is missing from navigation is not shown.
• mint validate runs in strict mode; fix warnings rather than ignoring them.
• Do not publish real API keys in examples; use environment variable names such as ACME_BILLING_API_KEY.
• Hand-written endpoint pages drift from the real API; prefer OpenAPI generation for anything larger than a few endpoints.
• Do not run mint dev on a port another project uses; pick one with --port.
• Mintlify is a hosted service. If you need a fully self-hosted site, use a static generator such as Docusaurus (mint export produces an offline zip for air-gapped viewing).