How to Build a Documentation Site with Mintlify in an Hour

October 30, 2026

Mintlify is a hosted documentation platform: you write MDX files in a Git repo, push, and get a docs site with built-in search, dark mode, code-block copy buttons and an AI question-answering widget. There is no design work and no theme to fight.

An hour is realistic for a docs site with 10-20 pages. Most of that hour goes into the navigation file, not the writing.

What does Mintlify need to run?

Three things: a GitHub repo, a docs.json navigation file, and MDX pages. That is the whole model.

MDX means Markdown with React components — so you get callouts, tabs and embedded OpenAPI endpoints without leaving prose. Each file gets frontmatter with a title and optional description, both of which feed the search index.

---
title: "Quickstart"
description: "Install the CLI and send your first request"
---

How do you set up the site?

  1. Install the CLI: npm i -g mintlify, then run mintlify dev in the folder with docs.json.
  2. Preview on localhost:3000. Hot reload works on file save.
  3. Create docs.json with a navigation tree — groups, pages, tabs.
  4. Push to GitHub, then connect the repo in the Mintlify dashboard.
  5. Set the subdomain (e.g. docs.yourproduct.com) via CNAME.

Preview-first is the right order. It takes 30 seconds to see a broken nav locally and ten minutes to debug it through a deploy.

How should you structure the navigation?

Group by user task, not by feature name. “Getting started / Core concepts / Guides / API reference” beats “Auth / Billing / Webhooks” for the reader who is new.

A practical docs.json snippet:

{
  "navigation": {
    "tabs": [
      { "tab": "Docs", "groups": [
        { "group": "Start here", "pages": ["index", "quickstart"] },
        { "group": "Guides", "pages": ["guides/deploy", "guides/webhooks"] }
      ]}
    ]
  }
}

Two habits that save time later: keep URL paths flat (guides/webhooks not docs/guides/core/webhooks), and never rename a page without adding a redirect in docs.json. Broken docs links are the top support ticket generator on every docs site.

Is Mintlify free?

Yes for the Hobby tier: unlimited public pages, one custom domain, and Mintlify branding in the footer. No credit card.

The paid Pro plan starts at $150/month per project and unlocks removing branding, custom domains per environment, API playground for OpenAPI specs, and analytics. Large pricing jumps are the standard complaint — going from $0 to $150 for branding removal is steep for a pre-revenue project.

If you only need a docs theme, Docusaurus is free and self-hosted. What you pay Mintlify for is the AI answer widget and the search relevance, which are genuinely better than the OSS alternatives at default settings.

Does the AI search actually help?

It reads your MDX and answers in the widget with citations to your pages. In practice it does well on “how do I rotate a key” questions and poorly on anything requiring your private knowledge base.

You can tune it by writing pages in question form — “How do I rotate an API key?” as an actual H2 — because the widget retrieves by section. That is the single highest-leverage change and it takes an afternoon.

Content warning: the widget will answer from your docs alone. If a page is vague, the answer is vague. Docs quality compounds harder here than on a normal site.

Where Mintlify is the wrong fit

  • You need a corporate intranet with SSO and role-based access. Mintlify Pro has SSO but not granular page permissions.
  • You host docs inside an existing WordPress or Next.js site. Mintlify hosts separate; using it as a subfolder is not really supported.
  • You have 200+ legacy pages with unique layouts. Migration cost exceeds the benefit.

Key Takeaways

  • Mintlify hosts MDX docs from a Git repo; pages get frontmatter with title and description.
  • Run mintlify dev for local preview before you ever deploy.
  • Hobby tier is free with one custom domain and footer branding.
  • Pro starts around $150/month per project — the steepest step is removing branding.
  • Write H2s as real questions; the AI search retrieves by section.