Skip to content
Skills Library
Programming · Building & coding

mintlify

/mintlify

Mintlify is a hosted documentation platform that turns MDX files and a docs.json config in a Git repository into a developer docs site with built-in search, an API playground generated from OpenAPI, and an AI assistant. Use this skill to create a documentation site, set up the mint CLI, write MDX pages with components, generate API reference pages from an OpenAPI spec, preview locally, validate and deploy; also to migrate an old mint.json project.

Repository
skills ↗
Licence
Apache-2.0
Last repository change
25.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
9
Deprecation

No signals detected. Repository changed on 25.10.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

Mintlify is a hosted documentation platform that turns MDX files and a docs.json config in a Git repository into a developer docs site with built-in search, an API playground generated from OpenAPI, and an AI assistant. Use this skill to create a documentation site, set up the mint CLI, write MDX pages with components, generate API reference pages from an OpenAPI spec, preview locally, validate and deploy; also to migrate an old mint.json project.

Original author description

Mintlify is a hosted documentation platform that turns MDX files and a docs.json config in a Git repository into a developer docs site with built-in search, an API playground generated from OpenAPI, and an AI assistant. Use this skill to create a documentation site, set up the mint CLI, write MDX pages with components, generate API reference pages from an OpenAPI spec, preview locally, validate and deploy; also to migrate an old mint.json project.

How it works

  1. Overview
  2. Instructions
  3. Examples
  4. Guidelines
Original SKILL.md headings · 137 lines, 869 words
SKILL.md preview
---
name: mintlify
description: >-
  Mintlify is a hosted documentation platform that turns MDX files and a docs.json config in a Git repository into a developer docs site with built-in search, an API playground generated from OpenAPI, and an AI assistant. Use this skill to create a documentation site, set up the mint CLI, write MDX pages with components, generate API reference pages from an OpenAPI spec, preview locally, validate and deploy; also to migrate an old mint.json project.
license: Apache-2.0
compatibility: 'Node.js 20.17+ for the mint CLI; a Mintlify account and a GitHub repository for deployment'
metadata:
  author: terminal-skills
  version: 1.1.0
  category: content
  tags: "documentation, mintlify, docs, api-reference, mdx"
---

# 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

```bash
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.

```json
{
  "$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>`.

````mdx
---
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>
```bash npm
npm install @acme-billing/sdk
```
```bash pnpm
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):

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

```mdx
---
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).
Files in this package (2)
  • SKILL.md 7 KB
  • _scores.json 2 KB

Versions

RepositoryScoreLicence
This page · TerminalSkills/skills100Apache-2.0
mintlify/docs100MIT
mintlify/mintlify-claude-plugin100MIT
gannonh/kata100MIT
cline/skills100Apache-2.0
mintlify/docs95MIT

Database snapshot: 13.11.2026 · package version 4be43bc76a71 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100write-docs
    Write BrowserOS feature documentation. Use when the user wants to create or update documentation for a BrowserOS feature. This skill explores the codebase to understand features and writes concise Mintlify MDX docs.
  • 100docs-incremental-update
    Incrementally update Mintlify documentation (.mdx) from Python source changes only. Use when: (1) Python files referenced in doc_code_map frontmatter have changed, (2) a PR touches Python modules documented in docs/mintlify/key_modules/ or docs/mintlify/mcp/, (3) the user asks…
  • 100docs-code-samples
    Use this skill when migrating inline code samples from LangChain docs (MDX files) into external, testable code files that are extracted by this repo’s snippet scripts and used as Mintlify snippets. Applies when extracting code blocks from documentation, creating runnable code…
  • 100docs-writing
    Write, rewrite, audit, or review a page of the Onyx customer docs (the Mintlify site in `documentation/`). Use for new pages, release refreshes, screenshot updates, connector and provider guides, API guides, docs edits in a feature PR, and docs quality reviews. Covers audience,…
  • 95validate-docs
    Validate and update the public user docs in `site/` (Mintlify) against the code — map every user-facing change since a ref to the pages it touches, fix the pages, then run the docs test, the Mintlify build and link checks and the anonymization scan. Also adds a release's…
  • 100writing-docs
    Guides for writing and editing Remotion documentation. Use when adding docs pages, editing MDX files in packages/docs, or writing documentation content.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.