Mintlify, documentation readable by humans and models

Mintlify, documentation readable by humans and models

Mintlify is a hosted platform for technical documentation. You write MDX files in a repository and get back a site with search, an interactive API playground and a set of outputs aimed at coding assistants. The engine is closed and covered by the Elastic 2.0 licence, the command line tool is at version 4.2.816, and the free plan is called Starter and gives you five editor seats.

What Mintlify actually does

The working model is simple, and that is where it differs from classic static site generators: the content repository is the source of truth, while building and hosting belong to the vendor. The directory holds .md or .mdx files, a single docs.json configuration file and optionally OpenAPI specifications. Once the repository is connected, every merged commit triggers a deployment on Mintlify's side.

Pages can be plain Markdown, but MDX opens access to components that plain Markdown lacks: cards, accordions, frames, fields describing API responses. The documentation explicitly suggests starting a migration from another platform with .md files and moving to MDX later, once the content already works.

The second leg is the API reference. You point at an OpenAPI or AsyncAPI file and the platform generates method pages from it together with a playground in which the reader sends a request straight from the browser. The API playground is available on the Starter plan already, as are a custom domain, the web editor, authentication and a hosted MCP server.

The third leg, and the most interesting one for this collection, is the set of outputs for language models. Mintlify hosts an llms.txt file, an llms-full.txt file, a Markdown version of every page under the same address with .md appended, an MCP server over the content, and a contextual menu that opens the current page in a chosen assistant.

What Mintlify does not do also deserves a plain answer. It is not an engine you can run on your own server on a free plan. It is not a content management system for a non-technical editorial team, although the web editor moves it in that direction. It will not replace a blog or a marketing site, because the whole layout is built around documentation navigation. It will not check for you whether the behaviour described in the text still matches the code, because the pages and the library live in separate repositories with nothing binding them automatically.

Version, licence and an empty spot on GitHub

The mint package in the npm registry is at version 4.2.816. It is a thin wrapper: it declares exactly one dependency, @mintlify/cli at version 4.0.1419, and the engines field requires Node 18 or newer. The mintlify package is published in parallel under the same number and contains the same tool.

The licence is the place where three sources should agree and one of them simply does not exist. The license field in the npm registry reads Elastic-2.0. The unpacked tarball contains a LICENSE file with the full text of Elastic License 2.0 and a copyright notice from Mintlify, Inc. dated 2022. The third source, the licence file in the repository, cannot be checked: the repository field in the manifest points at github.com/mintlify/mint, and the GitHub API answers that address with a not-found message. The engine source is not public.

That distinction is easy to miss, because the mintlify organisation has several MIT-licensed repositories on GitHub. The mintlify/starter repository, the skeleton of a new project, has around 1.9 thousand stars. The mintlify/docs repository with the content of the official documentation has around 435 stars, and mintlify/components around 114. All three are open, none is archived, and none contains the engine. The template and the content are open; the program that renders them is closed.

Elastic License 2.0 itself is a source-available licence rather than an open one in the OSI sense, and its central limitation is stated bluntly: you may not provide the software to third parties as a hosted or managed service that gives users access to a substantial set of its features. For a team that simply builds its own documentation, that clause carries no practical weight. It matters for anyone who would like to build a competing service on this engine, and for a legal department that keeps a list of dependency licences and treats anything beyond MIT, Apache and BSD as an item requiring separate review.

One more thread belongs to the picture of the company. In March 2026 Mintlify acquired Helicone, an observability layer for language model calls. The product moved into maintenance mode, which we describe in detail in the piece on Helicone, and teams looking for an alternative today usually land on Langfuse. For judging Mintlify itself this is information about direction: the company buys pieces of the puzzle around working with models and consolidates them, and acquired products do not always keep receiving development. If you build on something the vendor can switch into maintenance mode, keep an exit plan. With documentation the exit plan is cheap, because the content is ordinary Markdown files in your own repository.

docs.json and project structure

The entire configuration sits in a single docs.json file in the project root. The minimal form requires four fields; the rest is optional.

{
  "$schema": "https://mintlify.com/docs.json",
  "theme": "mint",
  "name": "Acme Docs",
  "colors": {
    "primary": "#1a73e8"
  },
  "navigation": {
    "groups": [
      {
        "group": "Get started",
        "pages": ["index", "quickstart"]
      },
      {
        "group": "Guides",
        "pages": ["guides/first-steps", "guides/advanced"]
      }
    ]
  }
}

The $schema reference is not decoration. It turns on autocomplete and validation in the editor, and with a file that runs to several hundred lines after six months, that is the difference between a fix in the editor and an error discovered at deployment time.

As the file grows, you can split it with the $ref field. You insert $ref with a relative path anywhere in the configuration and Mintlify replaces the object with the contents of the referenced file at build time. The rules are strict, and it is good that they are documented: paths must be relative and stay inside the project root, so ../../outside gets rejected, circular references end in a build error, and sibling keys in the same block override whatever came from the file referenced by $ref.

Every page starts with a YAML block. The fields are optional, but a few of them decide behaviour that is hard to reconstruct from memory later.

---
title: "Setting rate limits"
description: "How to configure request limits for an API key"
sidebarTitle: "Rate limits"
icon: "gauge"
tag: "beta"
noindex: false
searchable: true
---

Page content in MDX with platform components.

The hidden: true field removes a page from navigation and implies noindex: true. The documentation warns that setting hidden: false produces undefined behaviour, so the field is either true or absent from the file. The noindex and searchable fields are easy to confuse: the first pushes a page out of site search, the sitemap, search engine indexing and assistant context, while the second only excludes it from on-site search and assistant context, leaving it visible to external search engines.

Documentation readable by models

This is the real advantage of the platform, and it is worth splitting into four separate mechanisms, because they get conflated.

The first is llms.txt, a file following the standard described at llmstxt.org, hosted automatically at the site root and additionally at /.well-known/llms.txt. It contains a list of every page as Markdown links with summaries, so an assistant reads the index first and only then fetches what it needs. A custom version of the file is possible, but the default one updates itself.

The second is llms-full.txt, the whole documentation content glued into one file. Scale makes the difference here and it is easy to check on Mintlify's own documentation: llms.txt weighs around 56 kilobytes there, while llms-full.txt weighs around 1.5 megabytes. The first fits into a model context without a second thought; the second needs chunking or search, and handing it to an assistant whole rarely makes sense.

The third mechanism is the Markdown version of a single page. You append .md to the address and receive the source instead of HTML. This article exists partly thanks to that: the documentation address with .md appended returns clean Markdown that can be read without fighting through layout tags, scripts and styles. For a coding assistant that is the difference between a few thousand tokens of content and a few tens of thousands of tokens of wrapping.

The fourth is the contextual menu, driven by the contextual field in docs.json. Options are switched on by identifier, and their order in the list sets their order in the menu.

{
  "contextual": {
    "options": [
      "copy",
      "view",
      "assistant",
      "chatgpt",
      "claude",
      "perplexity",
      "mcp",
      "cursor",
      "vscode",
      "download-spec"
    ],
    "display": "toc"
  }
}

The copy identifier copies the page as Markdown, view opens it as Markdown, claude starts a conversation in Claude with the current page as context, cursor installs your MCP server in Cursor, and download-spec downloads the OpenAPI specification and appears only on API reference pages. The download-pdf option exists but is marked as available on Enterprise plans. Setting display to toc moves the menu from the page header into the table of contents sidebar.

Command line: preview, validation and mint score

The tool installs globally or runs through npx, and the command set is wider than the name suggests.

# installation and local preview, default port 3000
npm install -g mint
mint dev --port 4000 --no-open

# skip OpenAPI processing when the specification is large
mint dev --disable-openapi

# strict-mode build, non-zero exit code on warnings
mint validate

# separate content checks
mint broken-links
mint a11y
mint format

# export the site into a self-contained archive
mint export --output docs-offline.zip

# score the site's readiness for agents
mint score docs.example.com --format json

The mint validate command replaces the deprecated mint openapi-check and also validates specifications referenced from docs.json, so this is the one that belongs in a continuous integration pipeline. The --groups flag lets you mock membership in user groups, which is the only sensible way to view content behind authentication without logging into a real account.

mint score stands apart: it queries a public address and issues a weighted readiness score for agents. The checks have readable names and show what the vendor considers important: llmsTxtExists, llmsTxtValid, llmsTxtSize, llmsTxtLinksResolve, llmsTxtFullExists, skillMd, contentNegotiationMarkdown, contentNegotiationPlaintext, mcpServerDiscoverable, mcpToolCount, openApiSpec, robotsTxtAllowsAI, sitemapExists, structuredData and responseLatency. Dependent checks fail along with the one they depend on, so a missing llms.txt topples several entries at once. The command requires signing in with mint login, but accepts any address, so you can also score someone else's documentation.

There is also mint index, which installs a hosted MCP server that indexes content across sites built on Mintlify and connects it to a client: --claude, --cursor, --vscode, --codex, --opencode, --windsurf or --zed. That is a different server from the one describing your own documentation, and confusing the two leads to surprise that the agent cannot see your pages.

Pricing, the free plan and self-hosting

The pricing page shows three plans. Starter costs zero dollars per month and gives five editor seats, the full platform, a custom domain, the web editor, authentication, an MCP server and the API playground. For a free plan that is a lot, because items usually reserved for paid tiers, namely a custom domain and an MCP server, are included from the start.

Pro is displayed at 450 dollars per month, with a switch above the price between monthly and annual billing, and only one number could be read from the raw page. Treat it as the figure shown by default and confirm the other one with the vendor before signing anything. The plan adds unlimited editor seats, an agent, an assistant, automations, preview deployments and admin APIs. That means the assistant answering reader questions inside the documentation is a paid feature rather than part of the free plan, and if that assistant is the reason you are choosing Mintlify, Starter is out immediately.

Enterprise carries a price on request and covers SSO, SCIM, role-based access control, a performance service level agreement, advanced insights and migration support. Self-hosting appears at this tier too. The documentation is honest here and states plainly that this is not a self-serve install but a scope agreed with the vendor's account team, typically measured in weeks. Deployment goes through an AWS CDK app or a Helm chart on AKS, GKE, OKE, OpenShift or any Kubernetes. The limitations are described just as clearly: model-related features ship disabled until your security team approves them, integrations that depend on Mintlify cloud services simply do not work, updates arrive as versioned releases that you deploy yourself, and you connect your own monitoring.

The pricing page also mentions credits for the first month, but does not state their number in the page content, so we do not state it either. If you are building a budget, that is the first question for the sales team.

Deployment does not have to mean a separate domain. Mintlify documents publishing docs under a subpath of an existing site, for example at an address ending in /docs, through server-side rewrite rules. If the main site runs on Next.js, that comes down to a single entry in the rewrites configuration.

Mintlify versus the alternatives

Choosing between a hosted platform and a generator you run yourself comes down to whether you would rather pay with money or with team time. Below are figures checked in package registries and on vendor pricing pages.

Starlight is a theme for Astro, so it arrives together with that whole build environment. Docusaurus differs from Mintlify chiefly in that its engine is open and runs on your own server, and documentation versioning and translations sit in the core. Two drawbacks are worth knowing: there is no search in the core and the standard route runs through Algolia as an external service, free only for public technical documentation once an application is approved, and the whole site is a React application, so a team without React inherits an ecosystem it did not ask for. Docusaurus and Starlight cost nothing beyond time: search, deployment, the API playground and model-facing outputs are assembled by you from plugins and external services. For a two-person team that is usually a few days of work plus a small ongoing maintenance tax. For documentation that is part of the product and changes daily, the arithmetic starts to favour a hosted platform.

Common mistakes

The first mistake is treating Mintlify as an open project based on the repositories visible on GitHub. What is open under MIT are the starter template, the documentation content and the component library. The engine is closed, released under Elastic 2.0, and the repository referenced in the package manifest does not answer publicly.

The second is planning a rollout on the Starter plan and discovering halfway through that the assistant, the agent and automations only begin at Pro. Read the plan feature list before migrating content, not after.

The third is hidden: false in a page's YAML block. The documentation describes that setting as undefined behaviour. To show a page again, you remove the whole field.

The fourth is confusing noindex with searchable. A page with searchable: false still lands in the sitemap and in external search engines, so this is no way to hide anything.

The fifth is leaving mint validate out of the continuous integration pipeline. Without it a broken OpenAPI specification or a dead link rides to production, because the local preview is more forgiving than a strict-mode build.

The sixth is feeding an assistant the entire llms-full.txt. For documentation the size of Mintlify's own, that is one and a half megabytes of text. The right path is the index, then individual pages with .md appended, or the MCP server.

The seventh is splitting docs.json with $ref paths that leave the project directory. Traversing up the tree is blocked, and a circular reference ends in a build error.

FAQ

Is Mintlify open source software?

No. The mint package in the npm registry carries the Elastic 2.0 licence, and the same licence text sits inside the published tarball. Elastic License 2.0 is source-available rather than open, and it forbids providing the software as a competing hosted service. The mintlify/starter, mintlify/docs and mintlify/components repositories are MIT-licensed, but they contain the template, the content and the components, not the engine.

What does the free plan give you?

The Starter plan costs zero dollars and covers five editor seats, a custom domain, the web editor, authentication, a hosted MCP server and the API playground. Outside it sit the agent, the assistant that answers readers, automations, preview deployments and the admin APIs, which begin on the Pro plan.

Do I have to write in MDX?

No. Pages can be plain .md files, and the documentation itself recommends that route when migrating from another platform so that the content moves first. MDX becomes necessary only when you want platform components such as cards, accordions or fields describing API responses.

How does documentation reach a coding assistant?

Through four routes. The llms.txt file at the site root provides an index of pages, llms-full.txt provides the whole content in one file, appending .md to an address returns the source of a single page, and the hosted MCP server lets an agent search the content with a tool. The contextual menu adds buttons that open the current page in a chosen assistant.

Can I run Mintlify on my own infrastructure?

Only on the Enterprise plan and only as an agreed deployment scope, not as a self-serve install. The available routes are an AWS CDK app or a Helm chart on AKS, GKE, OKE, OpenShift or any Kubernetes. Model-related features are disabled by default in that setup, and integrations that depend on the vendor's cloud do not work.

What did Mintlify do with Helicone?

It acquired the company in March 2026 and moved the product into maintenance mode, meaning no new features. The self-hosted edition stays under Apache 2.0 and the Helicone/helicone repository is not archived. We cover the details separately in the piece on Helicone.

You will find the configuration and the full field list in the Mintlify documentation, pricing on the plans page, and the skeleton of a new project in the starter repository.