DEV Community

Alex Spinov
Alex Spinov

Posted on

Mintlify Has a Free API — Here's How to Build Beautiful Developer Documentation in Minutes

#mintlify #documentation #api #devtools

A developer advocate told me: 'We spent 6 months building custom docs with Next.js. Then Mintlify launched — our competitors had better docs in 2 days.' Documentation is the first thing developers judge your product by.

What Mintlify Offers for Free

Mintlify free tier:

  • Unlimited pages
  • Custom domain
  • API playground — interactive API reference from OpenAPI spec
  • Search — built-in full-text search
  • Analytics — page views, search queries, feedback
  • MDX support — React components in Markdown
  • Git-based — deploy from GitHub/GitLab
  • Dark mode — automatic
  • i18n — multi-language support

Quick Start 

npx mintlify@latest init
# Creates docs/ directory with starter template

cd docs
npx mintlify dev
# Preview at http://localhost:3000
Enter fullscreen mode Exit fullscreen mode

Configuration (mint.json) 

{
  "name": "Your Product",
  "logo": { "dark": "/logo/dark.svg", "light": "/logo/light.svg" },
  "favicon": "/favicon.svg",
  "colors": {
    "primary": "#3B82F6",
    "light": "#60A5FA",
    "dark": "#1D4ED8"
  },
  "topbarLinks": [
    { "name": "Dashboard", "url": "https://app.yourproduct.com" }
  ],
  "tabs": [
    { "name": "API Reference", "url": "api-reference" },
    { "name": "SDKs", "url": "sdks" }
  ],
  "navigation": [
    {
      "group": "Getting Started",
      "pages": ["introduction", "quickstart", "authentication"]
    },
    {
      "group": "Guides",
      "pages": ["guides/webhooks", "guides/rate-limits", "guides/errors"]
    }
  ],
  "api": {
    "baseUrl": "https://api.yourproduct.com",
    "auth": { "method": "bearer" }
  }
}
Enter fullscreen mode Exit fullscreen mode

Write Docs (MDX) 

---
title: 'Quick Start'
description: 'Get up and running in 5 minutes'
---

## Installation

<CodeGroup>
Enter fullscreen mode Exit fullscreen mode


bash npm
npm install @yourproduct/sdk

Enter fullscreen mode Exit fullscreen mode


bash yarn
yarn add @yourproduct/sdk

Enter fullscreen mode Exit fullscreen mode


bash pnpm
pnpm add @yourproduct/sdk

</CodeGroup>

## Initialize
Enter fullscreen mode Exit fullscreen mode


javascript
import { Client } from '@yourproduct/sdk';

const client = new Client({ apiKey: 'YOUR_API_KEY' });


<Note>
  You can find your API key in the [Dashboard](https://app.yourproduct.com/settings).
</Note>

<Steps>
  <Step title="Create a project">
    Navigate to the dashboard and click "New Project".
  </Step>
  <Step title="Add your first resource">
    Use the SDK to create your first resource.
  </Step>
  <Step title="Deploy">
    Push to production with one command.
  </Step>
</Steps>
Enter fullscreen mode Exit fullscreen mode


yaml

API Reference (From OpenAPI) 

# openapi.yaml — Mintlify auto-generates interactive docs
openapi: 3.0.0
paths:
  /users:
    get:
      summary: List users
      parameters:
        - name: page
          in: query
          schema: { type: integer, default: 1 }
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
Enter fullscreen mode Exit fullscreen mode

Custom Components 

{/* Built-in components */}
<Card title="Authentication" icon="lock" href="/authentication">
  Learn how to authenticate with the API
</Card>

<CardGroup cols={2}>
  <Card title="REST API" icon="code">
    Full REST API reference
  </Card>
  <Card title="SDKs" icon="cube">
    Official client libraries
  </Card>
</CardGroup>

<Accordion title="FAQ: Rate Limits">
  Free tier: 100 requests/minute.
  Pro tier: 1,000 requests/minute.
</Accordion>

<ResponseField name="id" type="string" required>
  The unique identifier for the resource
</ResponseField>
Enter fullscreen mode Exit fullscreen mode

Deploy 

# Push to GitHub — Mintlify auto-deploys
git add .
git commit -m "Update docs"
git push
# Live in ~30 seconds
Enter fullscreen mode Exit fullscreen mode

Why Mintlify

Mintlify Custom Docs Site
30-second deploy Hours of build config
Built-in search Add Algolia
API playground Build from scratch
Analytics included Add analytics tool
MDX components Build your own

Need to document your scraping APIs? Check out my web scraping actors on Apify — with clear API docs.

Need developer documentation? Email me at spinov001@gmail.com.

Top comments (0)