We've been writing developer documentation for over a decade. During that time, we've cycled through more documentation platforms than we’d like to admit: including various off-the-shelf documentation framework providers and building our own custom docs framework. Plenty of lessons were learned along the way.

TL;DR: If you’re reading this post, you’re most likely not from a huge company like Supabase, so just use Mintlify 😊

What we all aim for in devtool documentation

Stripe sets the gold standard for developer documentation. Their product is so deeply integrated with their docs that the two feel inseparable, showcasing the product in ways no generic framework could support.

As builders, it’s tempting to chase that level of quality by creating a custom documentation system from scratch. After struggling with the limitations of a SaaS docs provider (Readme.io at the time), we decided to do just that: develop our own React-based docs framework to deliver the experience we had in mind.

Table stakes

Even though we aspired to reach Stripe’s standard, the main reason we built our own docs system was that no existing framework offered the baseline features we considered essential for developer documentation. Here’s what we saw as the table stakes:

• Good versioning support. Whether it’s SDK, API or library versions, your docs will drift across these versions, and you want to make it easy for developers to switch versions.
• Link management tools:
  
  • You will want to write a page once and then reference it in multiple places using backlinks (basically the ability to easily refer to other pages within your docs).
  • When changing a page’s slug, you’ll want an easy way to manage redirects.
  • Nothing kills trust faster than clicking a link in the docs and getting a 404. Makes you wonder what else is broken. Gotta have broken link detection.
• GitHub/git integration. Most of us are engineers and want to use the same tools we’re already used to.
• A rich collection of specialized components for embedding code in your docs (e.g. code snippets with tabs / code groups).
• A way for users to contribute to our docs.

That covers developer experience, but there were operational requirements too:

• Analytics. We want to know which areas of our product are the most popular, and which users have most questions about. This is just one more thing you’ll need to wire up and maintain if you’re building yourself.
• Easy to use and maintain: We’re a small team with no dedicated docs roles, so writing and improving docs is something almost everyone in the team needs to be able to jump in on. Fixing a typo in our docs should be something anyone from our leadership to engineering teams can do while waiting for attendees to join a Zoom call.

And so, with a clear idea of what we wanted, confidence that no existing framework could give us that, and the long-term goal of Stripe-level integrated docs, we set out to build our own system.

Why you shouldn’t build your own documentation framework (in 2025)

In our product, PowerSync, we have the concept of the “network tarpit” — instead of working on core features, app developers are kept busy wrangling state management frameworks and network calls. We felt we had hit an analogous “custom framework tarpit”:

• Once you build a docs framework, you need to:
  
  • maintain it and the deploy pipeline
  • fix bugs
  • add features such as broken link detection
  • all of the above distracts from core product engineering work
• For users of the framework:
  
  • initial setup of toolchain can be tricky
  • no such thing as “make a quick change”
  • previewing changes in a staging environment as a whole other environment that needs to be managed

After too many cycles spent building our docs framework instead of our product, we admitted failure and made the humbling decision to mothball it and move to GitBook.

This was an immediate improvement. However, as we built out our docs over many months, we started to get worrying reports from users that our entire docs site was crashing. This would specifically happen on medium length pages with multiple code snippets:

After months of back and forth with their team, we couldn’t find a solution. In the end, the best workaround to prevent crashes was to disable syntax highlighting across our entire site. We found that, oddly enough, syntax highlighting was being done on the server and not on the client. This was rough for us.

Interestingly, while writing this post we discovered that Supabase has this very same issue (although the page in the video below is 20x longer than our longest page). We’re also not sure whether GitBook has resolved this issue or not.

So, after all that, someone in the team suggested we check out Mintlify, which brings us to the next section…

Why Mintlify is Awesome

After in-depth journeys across all the options (Readme.io → custom → GitBook → Mintlify), we are all Mintlify maximalists at this point (to be clear: Mintlify did not ask or otherwise encourage us to write this post). Their entry-level tier can be quite stiff for early stage startups, but their Hobby plan is so feature rich, we’d actually recommend that over something like VitePress at this point. It will save you time at every corner.

Some things that really stood out for us about Mintlify:

First off, Mintlify spun up a demo of our existing docs overnight. It made it very easy to evaluate them in a real context, and saved us a lot of time. When that’s your first experience with a service it’s pretty hard to ignore.

We immediately noticed that our pages loaded much faster, including our bulkiest page with lengthy code snippets and syntax highlighting. Again, having the demo from Mintlify which included the majority of our content was important for this, as performance is not something we could have accurately tested had we just built a POC.

We didn’t really need much more selling after this, but for completeness sake, these are the other main boxes that Mintlify checked for us:

• They offer a git-based workflow in addition to a web-based WYSIWYG editor. Why this matters: For larger updates the git-based workflow is a must as we already mentioned. But if we quickly want to fix a typo or make a small update, and especially if we want to encourage anyone in the team to help with this, being able to do this easily and quickly in a web editor is super helpful.
• Excellent customer service: we could easily ask them questions as we onboarded. With their help we had our site converted in a matter of days and they remained pretty responsive once we were live.
• Extensive component library: We have yet to come across a component we want to use in our docs that Mintlify doesn’t support. We especially liked their various navigation options, e.g. grouping content into tabs, as well as having a sidebar means we can allow our readers to get anywhere in just a single click, without having one long overwhelming list of pages.
• They’ve released tooling to help LLMs parse our docs so we didn’t have to do anything on that front to let the robots understand our docs. Out of the box we got options like llms.txt and the ability to copy pages in markdown for prompt contexts.
• Also, our docs just looked really good.

We feel our JavaScript SDK reference page showcases a lot of what we discussed in this post, see for yourself.

It’s a big page, with a lot of code, but stays super responsive no matter where in the page you are. It uses a wide range of widgets, including Mintlify’s contextual component for LLMs.

Our users can easily contribute by clicking on Suggest Edits which takes them directly into a PR workflow on our docs repo.