Is ReadMe worth it in 2026? Six objections, answered

Six complaints about ReadMe come up again and again in threads where people explain why they passed or left: no staging, no fit with Git pipelines, a shallow hierarchy, raw HTML for basic formatting, $400 a month for custom CSS, and a page per endpoint. Five describe a product that doesn't exist anymore. The sixth is a real tradeoff, and the last section says who should buy something else instead.

If you evaluated ReadMe before mid-2025, you were evaluating a different tool. Branches, reviewable previews, Bi-directional sync, a CLI, and a rebuilt editor all shipped after most of that criticism was written.

Does ReadMe have staging and review branches?

No staging, and no review branches visible in the app: that was a fair description of ReadMe as recently as late 2025, and it's still the version of this complaint we hear most.

It doesn't describe Branches, which shipped in August 2025 and lets admins save changes across pages without them going live. Every branch gets a Shareable Branch URL a reviewer can open without an account for seven days, and AI Branch Reviews added a Review tab with a line-by-line diff, covering reordering as well as content. On Enterprise, Reviews can be required: a Group Admin decides who can approve and who can merge, so an editor submits a branch and an admin publishes it. (Admins keep a Skip Requirements override, worth being deliberate about who gets it.)

Worth naming the actual tradeoff, since people mean two different things by staging. If you meant a gate before publish, that's what this is, and it's enforceable. If you meant one fixed URL you can always point a stakeholder at, we didn't build that: branches give you as many in-flight previews as you have work in progress, and the cost is that there's no single canonical staging link. If your process depends on a named URL rather than a gate, raise it with us directly.

Worth knowing where this actually sits next to everyone else, too, since "we caught up" isn't the whole story. GitBook has a comparable gate: Merge rules there can require review from specific teammates before anything ships, so on that one dimension it's closer than "we have it and they don't." Where the gap is real is Mintlify, where the equivalent step lives in GitHub's own branch protection. It exists once your team configures it there. Ours ships on for every project by default.

Does ReadMe work with Git, GitHub, and CI?

The other half of that complaint: ReadMe doesn't fit our pipelines. The answer is that we rebuilt the content layer on Git.

Bi-directional sync means changes in the ReadMe editor sync to your repository and changes in your repository sync back. Branches created in GitHub show up in ReadMe and the reverse. Navigation lives in _order.yaml files in the repo, so structure is reviewable in a pull request like anything else. GitHub Enterprise, including on-prem, was part of the June 2025 launch.

The new ReadMe CLI landed May 7, 2026. lint catches broken links, duplicate slugs, invalid frontmatter, and broken MDX components, with auto-fix. oas:sync keeps reference pages current with your spec, setup:github wires up a GitHub Action, and dev, in beta, runs a local server with hot reload.

Engineers didn't want to leave their editor. Now they don't have to.

Branches also picked up rebasing and dedicated conflict-resolution tools on September 18, 2026: you can bring a long-running branch up to date, or resolve a conflict, from inside the editor or by handing it to the AI agent, without ever opening a terminal. That's not "nobody else can rebase" — anyone working straight out of GitHub already has git itself. It's for the teammate who isn't fluent in git and would otherwise have to go find someone who is.

How many levels of nesting does ReadMe support?

The hierarchy cap is a 2023 complaint that gets worse as a product suite grows, and it's still the top public answer to this question. The sidebar went from three levels to five on June 26, 2026.

API Reference is a different answer, and the distinction matters more than the number. Reference structure is generated from your OpenAPI document: a category per document, pages from your tags, a page per operation. Three levels, because three levels is what a spec describes. OpenAPI has no way to express a tag inside a tag, so there's no fourth level for us to generate. Markdown subpages nest underneath a reference page fine, which is where a longer explanation of one operation belongs. What you can't do is ask us to invent a hierarchy your spec doesn't contain.

The more useful admission is why anyone would still believe the limit is two. That change was in our changelog and nowhere else. So the 2023 complaint is still the best available public answer to a question we fixed, and that's a documentation failure, from a company that sells documentation.

Can you style pages without writing raw HTML?

The same-era complaint on formatting: images couldn't be placed inside a paragraph or aligned without dropping into raw HTML.

That editor is gone. The engine moved from Slate to Tiptap in the May 2026 release, which is also where Inline AI and Full Preview Mode arrived. Pages support MDX, so you can write JSX directly on a page and style an <img /> however you want. Tabs, Accordion, Columns, and Cards come from the command menu, and Custom Components let you build one in Settings and reuse it.

An icon aligned to a line of body text is a component you write once and reuse now. Better than raw HTML on every page, not the same as a button.

"A whole lot of extra clicking"

From a 2023 roundup of every API docs platform the author could install: splitting each endpoint onto its own page looks cleaner and costs you the ability to hit Cmd-F across the whole reference.

This is the one we'd choose again, so it's worth saying what the choice is for.

A page per endpoint is an addressable unit. It's what lets Try It! sit next to one operation with its own auth and parameters, what makes an endpoint linkable so support can send someone to the exact failing call, and what lets the Developer Dashboard tie a logged request to the page someone was reading. A single-page reference gives you one Cmd-F. It gives up all three.

So we made finding things better than Cmd-F instead. Since June 26, 2026, search matches inside your API Reference: parameter names, request and response schema property names, and their descriptions, not only endpoint titles. Cmd-F on one long page only finds what's currently rendered, so a collapsed schema property is invisible to it. Jump To sits at the top of the API Reference sidebar at Cmd+/ and filters straight to an operation.

The other need underneath the complaint was getting the reference somewhere you can read or paste it. That one's a button now. Copy Page sits on every page, and its menu will view the page as markdown, open it in ChatGPT or Claude, or connect the hub to Cursor or VS Code over MCP. No account required, because the developer evaluating your API doesn't have one yet.

Your hub has two audiences now, and the one that doesn't click is the one that grew.

How much does ReadMe cost?

A 2023 roundup put us at $400 a month with custom CSS as the reason to upgrade. That number is stale: the price came down and those plans no longer exist.

Checked on readme.com/pricing September 17, 2026, Pro is $250 a month billed annually and Custom CSS & HTML is included, not a line item. Starter is free and ships Bi-directional sync, an interactive API Reference, a custom domain, LLMs.txt, and MCP Server, so you can connect your repo and publish a working hub without talking to us.

GitBook, Mintlify, and Redocly checked on their own pricing pages September 11, 2026, for a team of five.

We're third of four. Redocly is here because it's what the writer in that roundup actually chose, and leaving it out would have made a more flattering table and a less useful one.

One clarification, because the word invites the wrong guess. Ask AI Lite is included on Pro and runs the same default model every ReadMe hub gets, so it isn't a weaker answer. What the $150 Ask AI add-on buys is choosing your own model and customizing the surface. If you don't need to pick the model, you're not missing answers at $250.

Two honest edges. Our flat rate covers five admins, so unlimited-seat pricing catches up with us somewhere around fifteen. And GitBook charges per site, which cuts the other way once you run several.

The premium over GitBook buys specific things, not a vague "more": a review gate that's on by default rather than something someone has to configure in GitHub, a Developer Dashboard that ties a logged request to the exact page and API key that generated it, and a Discoverability score checked against an independent agent-readiness spec rather than a plain "we support AI" claim. Some teams won't need all three. If you do, that's what the gap is paying for.

Want the full side-by-side? We keep one each for Mintlify and GitBook.

One decision explains five of these

Read the six objections next to each other and they look like six unrelated gaps. They were mostly one.

No staging, no reviewable branches, no fit with a pipeline, structure you couldn't rearrange, an editor you couldn't escape into your own tooling: those are all the same complaint about a content layer that lived in a database and could only be reached through a web app. So we rebuilt it on Git. Every save is a commit, branches are real branches, navigation is a file, and the CLI exists because once content lives in a repo, a command line is the obvious way to reach it.

That matters if you looked at ReadMe once and moved on. These weren't five feature requests we worked through one at a time. They all fell out of moving content into Git, which is why they landed together, and why an impression formed before that rebuild is wrong about all of them at once.

Who should buy something else

Worth being precise about the money first, since the numbers get repeated wrong. Starter is free. Pro is $250 a month, so $3,000 a year. Five figures is the Enterprise conversation, and it usually starts with multiple sites or governance rather than page count.

ReadMe is the wrong call if you want full control of the frontend and have an engineer who wants to own it, if you need several separate sites without an Enterprise budget, since Pro covers one project, or if your docs are small and slow-moving enough that nobody will resent maintaining a static site. In those cases the r/golang thread and the r/node roundup are giving you good advice, and Docusaurus, Material for MkDocs, or Scalar will serve you. Docs behind a login is the one requirement on that list a static site generator will make hard.

ReadMe is probably the right call if your API is the product, if guides and a changelog and a support forum belong in the same place as your reference, if more than a couple of people touch the docs and someone has to approve what ships, if you need to see what developers actually called and what failed, or if you're being asked how your docs behave for agents and don't have an answer.

Come back and check

We'd rather be evaluated on what we ship than on what we shipped in 2023. So the ask is small: take the one thing that stopped you and check it. Starter is free and syncs with your repo, which means you can test the specific objection yourself.

Have a hub you gave up on, or an objection that isn't in these six? Send it to support@readme.io and we'll tell you straight whether it's fixed.

FAQ

The specifics, answered directly.

Is custom CSS extra on ReadMe?

No. Custom CSS & HTML is on Pro, not a separate charge. Checked on readme.com/pricing September 17, 2026: Starter is free, Pro is $250 a month billed annually with up to five admins and $20 each after, Enterprise is custom and annual.

Is ReadMe more expensive than GitBook, Mintlify, or Redocly?

Cheaper than two, more than one. Checked on each vendor's own pricing page September 11, 2026, for five people: Redocly Enterprise $120 at $24 per seat with AI search gated to that tier, ReadMe Pro $250 flat with Ask AI Lite included, GitBook Ultimate about $297 with a 500-answer soft cap, Mintlify Pro $450 with its assistant included.

What do I get on the free plan?

Enough to publish a real hub: one project on your own domain, the reference generated from your spec, Git sync in both directions, usage metrics, LLMs.txt, and MCP Server. What starts on Pro is Branches, Multiplayer editing, Ask AI Lite, unlimited published versions, and Custom CSS & HTML.

Can agents and LLMs read a ReadMe hub?

Yes, and without an account. Copy Page will view any page as markdown, open it in ChatGPT or Claude, or connect the hub to Cursor or VS Code over MCP. Appending .md to a page URL also returns markdown, and every hub publishes LLMs.txt. If you want a number instead of taking our word for it, Discoverability scores a hub against an independent agent-readiness spec, not one we invented and grade ourselves against, and you can run the check on your own hub in a few minutes.