Mintlify vs GitBook for a developer portal
Start with Mintlify Free if a small team owns its public developer docs in Git and needs a branded site with interactive API examples. Start with GitBook Essential if technical writers need to propose, review, and merge changes in a visual editor while engineers still work in Git. Both can publish an interactive OpenAPI reference. The choice is who controls the merge and what happens when the API spec changes after a release.
| Decision | Mintlify | GitBook |
|---|---|---|
| Start for free | Five editors, custom domain, Git sync, and API playground | One user, block editor, Git Sync, and interactive API docs |
| Branded public collaboration | Custom domain included on Free | Essential adds a custom domain and team collaboration |
| Release preview | Hosted pull-request preview deployments on Pro or Enterprise | Preview deployments listed on Free; team review uses change requests on plans with collaboration |
| Where the API spec lives | File in the docs repo or public HTTPS URL referenced in docs.json | Upload, a hosted URL, or CLI publishing to a registered spec |
| First paid price | Pro $540 monthly or $450/month billed annually, unlimited editors | Essential $79/site plus $15/user monthly, or $65/site plus $12/user per month billed annually |
The comparison is for one site unless otherwise stated. The Mintlify pricing page and GitBook pricing calculator use different billing units. The rows are not a claim that the plans offer identical preview controls or access management.
How a documentation change reaches production
Mintlify: put a reviewed change on a branch. The web editor publishing guide documents different behavior on the deployment branch and on feature branches. Without protections, publishing on the deployment branch can put an edit straight into production. When the deployment branch requires pull requests, the editor can move an edit to a branch for review and merge. A writer does not have to leave the browser to start the change, but the team should verify that its required reviewers and checks apply before the public build. Watch for auto-publish: Mintlify documents that it cannot be enabled at the same time as the editor's required-review setting.
Mintlify's hosted preview deployments require Pro or Enterprise. A free local preview can help an engineer check a page, but it doesn't give a partner or writer a hosted link to inspect. Decide whether a shareable build is a requirement or a convenience. Test a preview created from the same pull request that will ship. A staging site on a different, long-lived branch can miss a broken file or navigation change in that release.
GitBook: ask who reviews the visual change. Git Sync keeps content synchronized in both directions with GitHub or GitLab. In the editor a writer can open a change request, collect comments, and merge into the live content after review. If your policy says every change must have an approval in Git, do not assume the approval on a GitBook change request is recorded as an approval on a Git pull request. Test the combination of GitBook roles, your repository's branch protection, and the intended way to publish before you switch. If the editor cannot write to the protected branch without an exception that your team will not grant, choose the Git-controlled workflow rather than quietly dropping the check.
OpenAPI refresh: test the second release, not the first import
Both services render endpoint pages from an OpenAPI description. For the trial, put the same non-production OpenAPI 3.1 spec and the same getting-started page into both tools. Use a spec with an example response, a required header, a shared schema, and at least one documented error. Verify the displayed request, the response example and the navigation. Do not use production credentials or real customer data in an interactive playground. Importing the file once isn't a test of how the examples will be maintained.
In Mintlify's OpenAPI setup, you reference a file path or public URL in docs.json. A spec version committed alongside the prose can be reviewed in the same diff. If you reference a hosted file, changing it does not by itself rebuild the site. Mintlify documents triggering a deploy after the new spec is published. Validate the spec locally or in CI before publishing, and bundle external schema references when Mintlify needs a single document. Do not publish an internal spec to a public repository or docs site merely to make the build fetch it.
In GitBook's OpenAPI setup, the spec is registered separately from Git-synced content. Upload a new file, link a hosted URL, or publish from CI with the CLI. GitBook checks a hosted spec every six hours; you can request an immediate refresh. If the API changelog and reference must update in the same release, the six-hour check is not a release guarantee. Use the immediate path, wait for the rendered change, and verify that the endpoint and the getting-started example agree before announcing it.
For a team still on Swagger 2.0, GitBook documents direct import for files, hosted URLs, and CLI publishing. Mintlify's OpenAPI guide says to convert Swagger 2.0 to OpenAPI 3.x. That can be harmless if the generated spec is already changing, but it is migration work if you must maintain a legacy SDK contract. Run your representative endpoints through the conversion rather than deciding based only on whether the viewer accepts a file.
Cost the team, not just the site
For two engineers and one writer on a public site, Mintlify Free can fit all three editors plus the custom domain and interactive reference. If they need hosted pull-request previews or add a sixth editor, the published Mintlify Pro rate is $540 month to month or $5,400 for a year ($450/month equivalent). Mintlify's 14-day Pro trial can show features that will not remain on Free. Record which actions the team actually needs after the trial, not what it happened to use during it.
On GitBook Essential, using the same three billed users on one site costs $79 + 3 × $15 = $124 monthly, or $65 + 3 × $12 = $101/month billed annually, totaling $1,212 per year. Six billed users on one Essential site cost $169 month to month or $137/month billed annually. Do not multiply the site fee by editor count, and do not compare the annual-equivalent rate with a short, month-to-month project without writing down the commitment. These figures exclude tax and additional usage. If you need a customer login on the published site, compare the quoted access features: GitBook lists authenticated access on Ultimate, not Essential; check the identity requirements before assuming the cheapest public plan fits.
Price the time lost to publishing separately. When a team ships twice a week, a writer waiting for an engineer to merge a copy edit is a recurring operating cost. When docs are tied to SDK revisions, a separate visual approval adds risk if it is not visible to the release owner. The cheaper plan only wins if it preserves the handoff you need. Do not price Pro for AI if the team mainly needs an editor and a regularly updated API reference.
Run a two-change trial before moving the domain
- Make one prose change as a writer. Edit an onboarding instruction without administrator rights, ask an engineer to review it, and check that the public site remains unchanged while it is pending. Approve it once and confirm the published result and the corresponding Git change. Record who could merge and whether the policy was enforced, not just whether a preview opened.
- Make one API change as an engineer. Change an example field in the spec and update one onboarding step. Keep the old spec available so you can revert. Verify the spec version on the resulting reference, time the interval to publication, and note any manual refresh or separately approved step. The important outcome is that a reader gets the new prose and the matching request example together.
- Test your exit path. Take one docs page with a relative link, a screenshot, and a vendor-specific interactive block. Check what can be saved in the repository and what would need replacement on another host. Exporting the prose isn't enough if the new host loses the image path or the API example. Inventory deep links and redirects on a small sample before transferring the public domain.
- Choose one owner for publication. Favor Mintlify when the same Git review can ship code-adjacent docs with the spec, and the editor count and preview needs fit budget. Favor GitBook when writers should own review and publication from the browser and the Git synchronization test preserves the team's required approvals. If neither platform can keep the prose and reference in step, fix the release workflow before moving the site.
If the job is internal notes rather than a public API portal, GitBook vs Obsidian compares a different ownership decision. If you keep Markdown and host it yourself, compare static hosting limits before moving the domain. For a library with live component examples rather than HTTP endpoints, compare component documentation tools instead of treating an OpenAPI playground as the same thing.