How to Use Mintlify: The Beginner's Guide (First docs.json, the Agent-Skill Workflow, and Your First Live Docs Site)

CodexFuse Team · 2026-11-07T09:11:48.026Z · 23 min read min read

How Do You Use Mintlify?

Learning how to use mintlify starts with one idea: Mintlify is the AI-native documentation platform that turns Markdown and MDX files in a Git repository into a hosted documentation site. You name a project, connect a repository, write pages in MDX, configure the site in one docs.json file, and Mintlify builds and deploys the site every time you push. This mintlify tutorial follows the official Mintlify documentation, and every fact in it was checked in November 2026.

A mintlify setup starts with the Git beginner guide idea of docs as code, because every page has a corresponding file in your documentation repository. You edit files locally or in the web editor, and the live site follows your repository. The seven steps below are the whole beginner arc in one list.

1. Create a Mintlify account and name your project at mintlify.com/start.
2. Connect a GitHub repository, or let Mintlify host the content in a private repository it manages.
3. Install the mint CLI with npm i -g mint on a machine with Node.js v20.17.0 or newer.
4. Create docs.json with a theme and a navigation section.
5. Write your first page in MDX and add it to the navigation.
6. Preview the site locally with mint dev at localhost:3000.
7. Push to your deployment branch and open your live site at your-project.mintlify.site.

What Is Mintlify, and What Is It Not?

Mintlify is the agent-led docs platform: docs.json holds the configuration, MDX files hold the content, and the platform turns them into LLM-friendly pages. The mental model is simple: your repository is the source of truth, docs.json is the map, and Mintlify is the publisher. Readers get search, an API playground, and an AI assistant on paid plans, while coding agents read the same docs as llms.txt.

Mintlify is not a static site generator you host yourself. The platform is a commercial hosted service, and the docs repository is MIT licensed content, not the platform itself.

Mintlify is not a word processor, and it is not a wiki with a database behind it. If you want full control over the build and the hosting, a self-hosted framework fits better, and the comparison later in this guide explains that trade.

The mintlify docs describe Mintlify as an AI-native documentation platform built for developers, with beautiful defaults, interactive API playgrounds, and smart search. That description matches the product: the defaults look finished with no theme work, the API playground runs requests from an OpenAPI specification, and the search understands documentation structure. The agent features are the newest part, and they get their own section below.

Two names cause confusion, so here is the split in one place. Mintlify Doc Writer is a VS Code extension that writes docstrings for code, and it is a different product from the docs platform. Mintlify Doc Writer writes code docstrings and is a different product from the Mintlify docs platform.

What You Need Before You Start

You need three things: a GitHub account or another Git provider, Node.js v20.17.0 or newer on your machine, and a few pages of documentation worth publishing. A GitHub account matters because Mintlify watches your repository and deploys on push.

Node.js matters because the mint CLI runs on it, and the official docs require v20.17.0 or newer. The documentation itself can be a single README plus a getting-started page to begin with.

You do not need a credit card to start. Starter is free, and the official pricing page says you can try Pro for 14 days with 5,000 credits and no credit card required.

You do not need a custom domain either, because every site gets a subdomain on mintlify.site. You do not need React skills, because pages are Markdown with optional MDX components.

Step 1: Create Your First Docs Site

Your first docs site starts at mintlify.com/start, where you complete onboarding and name the project. The official quickstart, updated October 31, 2026, promises a deployed documentation site in minutes.

After onboarding, the site is live at your-project.mintlify.site, and the dashboard Overview page shows the address. As of November 2026, every fact in this guide was checked against the sources named in the Sources section.

Connecting GitHub is optional during onboarding. If you connect it, you install the Mintlify GitHub App and pick the repository, and pushes to the deployment branch deploy automatically.

If you skip it, Mintlify hosts your content in a private repository it manages, and you can move to your own repository later from the dashboard Git Settings page. The GitHub beginner guide covers the repository side of this step if GitHub is new to you.

The agent-led path is the first option the quickstart presents. You give your coding agent the quickstart and ask it to create and deploy the site, while you complete email verification and any GitHub authorization in your browser.

The agent runs the CLI setup workflow, and you stay in control of the account steps. This is the same agent-skill workflow covered in detail later in this guide.

Step 2: Write Your First docs.json

A mintlify docs.json file is the single root configuration file for your site, and it holds the theme, the fonts, the navigation, the redirects, and the SEO settings. Only two fields are required: theme and navigation. Everything else is optional, so a beginner file can be short and still build.

The navigation section lists your pages by file path without the file extension, so a page at getting-started/welcome.mdx appears as getting-started/welcome in the navigation. Groups hold pages, and the navigation can also hold tabs, anchors, dropdowns, and languages. Large sites can split the configuration across files with the $ref keyword, and one real docs.json grew past 21,000 lines before its owners split it.

The mint.json file is deprecated in favour of docs.json. The mint upgrade command creates a docs.json from an existing mint.json, and the new file adds a top-level theme field. Many ranked tutorials still teach mint.json, and following them will teach you a workflow Mintlify has moved past.

{
  "$schema": "https://mintlify.com/docs.json",
  "theme": "mint",
  "name": "Acme Docs",
  "navigation": [
    {
      "group": "Getting Started",
      "pages": [
        "introduction",
        "getting-started/welcome"
      ]
    }
  ]
}

The example above is a complete beginner docs.json with one group and two pages. The theme value picks the visual theme, the name value is the site name, and the pages list is the order readers see in the sidebar. Add a page by writing the MDX file and adding its path to this list.

Step 3: Write Your First Page in MDX

Your first page is a Markdown file with a small block of frontmatter at the top, and MDX lets you add React components when plain Markdown is not enough. The frontmatter holds the title, the description, and optional fields such as the sidebar title, an icon, a tag, and keywords. A page with a clear title and a one-sentence description is already well formed.

Mintlify ignores README, CONTRIBUTING, CHANGELOG, and LICENSE files by default, so your docs folder needs a real first page. If your docs folder only has a README, the agent setup adds an index page for you. The .mintignore file beside docs.json excludes files with gitignore syntax, so generated files stay out of the site.

Write for the reader who arrived from a search result, not for the reader who already knows your product. One page should answer one question, start with the answer, and keep paragraphs short. The navigation entry you added in docs.json is what makes the page findable, so check the sidebar after every new page.

Step 4: Preview Locally With mint dev

Local preview starts with one install command and one preview command, and both use the mint package. Install the CLI globally with npm i -g mint, then run mint dev from the directory that holds docs.json, and open localhost:3000 in your browser. The preview updates as you edit, so you can catch broken links and layout problems before anything deploys.

Do not install the older mintlify package by mistake. The official open-source publishing guide warns about this exact mix-up, and the old package teaches the old workflow.

The mint package is the current CLI, and its latest version on the npm registry is 4.3.3 as of November 7, 2026. The mint dev command is a local preview only, not hosting.

node --version
npm i -g mint
cd docs
mint dev

The four lines above are the full local workflow: check Node.js, install the CLI, move into the docs folder, and start the preview. Use mint update when the CLI itself needs a newer version, and use mint validate from the docs folder to check docs.json before you push. The mint broken-links command finds dead internal links, and mint format keeps the files tidy.

Step 5: The Agent-Skill Workflow

With mintlify agent skills, a coding agent can set up and maintain your docs, because the skill teaches the agent how Mintlify projects work. Install the skill with the command below, start a fresh agent session so the skill loads, and then ask the agent to turn your Markdown into a Mintlify site. The agent creates docs.json, builds the navigation from your existing files, and runs mint validate and mint broken-links before it reports back.

npx skills add https://mintlify.com/docs
mint agent setup

The agent-skill workflow is the 2026 way to use Mintlify, and it replaces the old habit of hand-writing every config file. A typical agent prompt names the docs folder, says to keep the page content unchanged, and tells the agent not to commit, push, or publish.

You review the diff, run the two CLI checks yourself, and then deploy. The skill already knows the page rules, so your prompt only needs the parts that are specific to your project.

Published Mintlify sites are LLM-friendly by design, and that is the point of the whole workflow. Every site serves llms.txt, a structured index of its pages capped at 100,000 characters, plus llms-full.txt with the whole site in one file.

Pro and Enterprise sites also get a skill.md file that agents install and use, and every site gets a hosted MCP server so agents can search the docs directly. Pages are sent to AI agents as Markdown instead of HTML, which is why agents can quote your docs accurately.

Mintlify reports that 78% of October 2026 traffic across Mintlify-powered documentation came from agents. The 78% agent-traffic figure is a Mintlify vendor claim, not an independent fact. Treat it as a signal about where documentation traffic is heading, not as a measured fact about your own docs, and remember that your own analytics will show your own mix.

Step 6: Deploy and Go Live

Deploying on Mintlify means pushing to your deployment branch and letting the platform build the site. The Mintlify GitHub App watches the repository, and a push to the default branch triggers a build and a deploy. Pull requests get preview deployments on paid plans, so reviewers can read the changed pages at a temporary URL before the merge.

The GitHub Actions beginner guide covers the automation side of this step, because Mintlify also ships a GitHub Actions path for teams that want checks in CI. The docs suggest a job that installs the mint package globally and runs mint format and mint validate, so broken navigation never reaches production. Paid plans can also turn on broken-link checks and prose linting as blocking CI checks.

The newest deploy path needs no account at all. An agent runs mint deploy with a subdomain, the CLI creates a Mintlify-hosted Git repository and returns a short-lived write token, the agent pushes the docs, and the site goes live at that subdomain on mintlify.site. The site must be claimed within 24 hours, and the GitHub Actions variant of the command only works for sites that are not yet claimed.

npm i -g mint
mint deploy --subdomain acme

A custom domain comes from the dashboard, and the setup asks for two TXT records first and then a CNAME to cname.mintlify.builders. DNS propagation can take up to 48 hours, and Mintlify manages the SSL certificate and renews it automatically. The canonical domain goes in docs.json under the SEO metatags, so search engines see one address for the site.

Mintlify Pricing: What Starter and Pro Actually Cost

The mintlify pricing story starts with a free Starter plan and a 14-day Pro trial with 5,000 credits, and no credit card is required for either. Starter costs 0 dollars per month and includes 5 editor seats, a custom domain, the web editor, authentication, an MCP server, and an API playground. Pro adds unlimited editor seats plus the Agent, the Assistant, Autopilot, preview deployments, and admin APIs.

The official pricing page shows no numeric Pro price in its text. The page renders the Pro price as a dollar sign with no number, so the dollar figures below come from third-party pricing trackers that checked the page in September and October 2026.

Those trackers agree that Pro costs 450 dollars per month billed annually, or 540 dollars per month billed month to month, and this guide reports that consensus as a third-party figure, not as an official price. Check the live pricing page before you budget, because the number can move.

The credit math is official and published on the pricing page. Pro includes 10,000 AI credits per month, overages cost 0.01 dollars per credit, and the Assistant costs 25 credits per answer while Autopilot and automations cost 250 credits per update.

Those rates turn into 400 Assistant answers or 40 Autopilot updates from the monthly allowance, and the 5,000-credit trial covers 200 Assistant answers or 20 Autopilot updates. Answers are free when the Assistant cannot answer, and updates are free when nothing needs updating.

Open-source projects get a separate path. The official publishing guide says to publish free on Starter and then apply for the OSS Program to get Pro free.

That is the honest free story: free hosting, a custom domain, and the web editor on Starter, with AI features behind Pro. Starter includes no AI features, so do not promise a free AI tier that does not exist.

The annual plan saves 1,080 dollars per year against monthly billing, which is 16.67 percent of the monthly-billing yearly total. Credit top-ups reported by one tracker cost 145 dollars for 15,000 credits, 370 dollars for 40,000, and 800 dollars for 90,000, so larger packs cost less per credit. Those top-up prices are third-party reports, and the official page only confirms that credit packs are available.

Annual billing totals 5400 dollars per year, monthly billing totals 6480 dollars, and the gap is 1080 dollars.

Mintlify vs Docusaurus: Which One Should You Pick?

The mintlify vs docusaurus comparison is the one most readers ask about, and the answer is about who owns the work. Mintlify is a hosted platform: you write MDX and docs.json, and Mintlify runs the build, the hosting, the search, and the AI features. Docusaurus is a self-hosted open-source framework: you own the React build, the hosting, the search wiring, and the maintenance, and you pay nothing in license fees.

Docusaurus is maintained by Meta, licensed under MIT, and its current version is 3.10.2 from July 10, 2026. Docusaurus figures in this guide are attributed to their sources, not independently checked.

Its GitHub stars sit near 64,000 to 66,000 across sources from 2026, which is roughly 140 times the 462 stars on the mintlify/docs repository. That gap measures the size of the communities, not the quality of either tool, because the mintlify/docs repo holds documentation content while Docusaurus is the whole framework.

Pick Mintlify when your team writes docs as code in Git and wants hosting, search, API playgrounds, and agent features without owning infrastructure. Pick Docusaurus when you want free, open-source docs you host yourself, full control over the React site, and no monthly SaaS fee. Mintlify ships a Docusaurus migration guide and a mint migrate command for the Docusaurus source, so the choice is reversible in one direction.

Mintlify Self-Host: Who It Is Really For

A mintlify self-host deployment runs Mintlify inside your own cloud or on-premises environment, on AWS or any Kubernetes platform. The official self-hosting docs say every self-hosted deployment is a scoped engagement with your account team, and that cloud-hosted sites go live the same day while self-hosted ones typically take a few weeks. Self-hosting is an Enterprise engagement, not a self-serve install.

The sizing shows why it is an engagement and not a download. A production deployment runs on roughly 45 to 60 vCPU, 160 to 220 GB of memory, and about 1 TB of solid-state storage across its services, while a non-production environment runs at about half that size. The stack includes MongoDB for content, PostgreSQL for metadata, Redis for the build queue, object storage for bundles, and an identity provider, and your team operates the cluster while Mintlify ships versioned releases.

Self-hosting fits teams with data-residency, compliance, or air-gap requirements that a cloud-hosted deployment cannot meet. AI features ship disabled until the customer security team approves them, and fully air-gapped environments use static export bundles with no Git connection. The Docker beginner guide covers containers in general, and what is VPS hosting explains the server side, but neither one is a Mintlify self-host guide, because there is no self-serve install to document.

Seven Mistakes Beginners Make With Mintlify

Most Mintlify failures come from following old guides, not from the platform being hard. The old workflow looks similar enough to waste an afternoon, and the table below lists the seven mistakes that cost beginners the most time. Each fix takes minutes once you know the current flow.

Sources

The facts in this guide come from the official Mintlify documentation and pricing page, the Mintlify GitHub organization, and the npm registry, all fetched on November 7, 2026. The quickstart was updated October 31, 2026, the CLI install page was updated October 30, 2026, and the self-hosting page was updated October 22, 2026. The pricing page was fetched the same day, and its text shows the Pro price as a dollar sign with no number, which is why the Pro dollar figures in this guide are labelled as third-party consensus from Scalar, Featurebase, and documentation.ai, checked in September and October 2026.

The repository figures come from the mintlify/docs page on GitHub, fetched November 7, 2026: 462 stars, 249 forks, 3 watchers, 4,735 commits, MIT license, created March 23, 2023. The CLI version 4.3.3 comes from the npm registry entry for the mint package, fetched the same day. The Docusaurus version 3.10.2 and its July 10, 2026 release date come from the Docusaurus changelog, and the Mintlify versus Docusaurus framing comes from the Context7 comparison and Mintlify own alternatives guide.

The repository is 1325 days old, or 3.63 years, which works out to 1.86 stars per fork and 3.57 commits per day. Docusaurus stars run about 140.7 times the mintlify/docs count at the 65000 figure.

The quickstart is 7 days old, the open-source guide is 12 days old, and the deploy blog is 10 days old. The CLI moved from 4.2.210 to 4.3.3 over 348 days.

The independent-guide picture comes from search results fetched November 7, 2026: the SpecBee guide and two dev.to guides teach the old mint.json and mintlify-package workflow, while the current end-to-end walkthroughs are Mintlify own quickstart and open-source publishing guide. The 78 percent agent-traffic figure, the 24-hour claim window for mint deploy, and the 45 to 60 vCPU self-hosting size all come from Mintlify own pages and are presented as vendor statements. No commands in this guide were executed in a live testbed.

A browser fetch of the mintlify/mint repository page returns a 404, so this guide cites no star count for the CLI. CodexFuse offers no Mintlify tool. No Facebook promotion applies to this article.

docs repo age: 1325 days = 3.63 years
stars per fork: 462 / 249 = 1.86
commits per day: 4735 / 1325 = 3.57
docusaurus stars vs mintlify docs: 65000 / 462 = 140.7
pro annual yearly: 450 x 12 = 5400 dollars
pro monthly yearly: 540 x 12 = 6480 dollars
annual saving: 6480 - 5400 = 1080 dollars = 16.67 percent
assistant answers per month: 10000 / 25 = 400
autopilot updates per month: 10000 / 250 = 40
trial assistant answers: 5000 / 25 = 200
trial autopilot updates: 5000 / 250 = 20
non-prod vcpu: 45 / 2 = 22.5 to 60 / 2 = 30.0
non-prod memory: 160 / 2 = 80 to 220 / 2 = 110 GB
quickstart age: 7 days, oss guide age: 12 days, deploy blog age: 10 days
cli gap 4.2.210 to 4.3.3: 348 days since 2025-11-24

Frequently Asked Questions

Is Mintlify free?

Yes, the Starter plan is free with 5 editor seats, a custom domain, the web editor, and an API playground. AI features such as the Assistant and the Agent are Pro features, so a free plan does not include them. New accounts can try Pro for 14 days with 5,000 credits and no credit card, and qualifying open-source projects can get Pro free through the OSS Program.

How do I install the Mintlify CLI?

Install it with npm i -g mint on a machine with Node.js v20.17.0 or newer, then run mint dev from the folder that holds docs.json. Do not install the older mintlify package, because that is the old CLI with the old workflow. The current mint package version on the npm registry is 4.3.3 as of November 7, 2026.

What is docs.json in Mintlify?

docs.json is the single root configuration file for a Mintlify site, and theme and navigation are its only required fields. It holds the theme, the fonts, the navigation, the redirects, and the SEO settings in one place. It replaces the deprecated mint.json file, and the mint upgrade command converts an old mint.json into docs.json.

Can I self-host Mintlify?

Self-hosting is available on Enterprise only, as a scoped engagement with your account team, not as a self-serve install. A production deployment needs roughly 45 to 60 vCPU, 160 to 220 GB of memory, and about 1 TB of solid-state storage. Most teams should stay on Mintlify cloud hosting, which deploys the same day.

Is Mintlify better than Docusaurus?

Neither is better in general, because they solve different problems. Mintlify is the faster choice when you want hosted docs with search, API playgrounds, and agent features without owning infrastructure. Docusaurus is the better choice when you want free, open-source docs you host yourself with full control over the React site.