Self-hosted or managed developer portals? when to choose

Your team needs a developer portal, the first decision isn't what to write or how to structure it. It's where the thing lives: self-hosted on your own infrastructure, or on a managed platform that handles hosting, deployment, and updates for you.

Get this wrong and you're either paying engineers to maintain documentation infrastructure they resent, or locked into a platform that can't flex when your product outgrows it. Both mistakes take months to unwind.

This post compares self-hosted vs managed documentation side by side: real costs, maintenance burden, platform lock-in, and the decision criteria that actually matter. We've built developer portals on both models across 100+ client engagements. This is what we've seen work.

What "self-hosted" and "managed" actually mean for documentation

A self-hosted developer portal runs on your infrastructure. You control the code, the hosting, the deployment pipeline, and the updates. A managed portal is a SaaS platform that handles all of that for you. You write the content. The platform handles everything else.

The terms get used loosely, so it's worth being specific.

Self-hosted

Self-hosted means you pick a framework, customize it, deploy it to your own servers or a CDN, and maintain it. The most common frameworks are Docusaurus (React-based, built by Meta), MkDocs with the Material theme (Python-based), Nextra (Next.js-based, tight Vercel integration), and Fumadocs (newer Next.js entrant, growing fast).

You own the code, you also own every dependency update, build failure, and infrastructure decision that comes with it. Most teams deploy to Vercel, Netlify, or AWS CloudFront and treat the portal like any other application in their stack.

Managed

Managed means platforms like Mintlify, ReadMe, GitBook, or Stoplight. You write in their editor or push markdown through a Git integration. They handle hosting, search, versioning, analytics, and design out of the box.

The trade-off is straightforward: you get speed and lower maintenance at the cost of customization and control.

The spectrum isn't binary

Some managed platforms blur the line. Mintlify lets you push from a Git repo and customize components heavily. Some self-hosted setups (Docusaurus on Vercel with automated deploys) are nearly hands-off after the initial configuration.

The real distinction isn't where the code lives. It's who is responsible when something breaks. If the answer is "our engineering team," it's self-hosted. If the answer is "the platform vendor," it's managed. That difference in ownership is what shapes everything downstream: cost, maintenance, and how much engineering attention the portal requires over time.

The real cost of self-hosted vs managed documentation

Self-hosted documentation has low upfront licensing costs (most frameworks are open source) but significant ongoing costs in engineering time, infrastructure, and maintenance. Managed platforms cost $100 to $500+ per month in licensing but eliminate infrastructure overhead almost entirely. Over a year, the total cost of ownership often converges.

The sticker price on each model is misleading in opposite directions.

Self-hosted costs

The framework is free. Docusaurus, MkDocs, Nextra, Fumadocs are all open source. That's the number people anchor on.

Hosting runs $20 to $200 per month depending on your setup. Vercel and Netlify have generous free tiers for smaller sites. AWS CloudFront or self-managed infrastructure costs more but gives you full control over caching, CDN configuration, and uptime SLAs.

CI/CD pipeline setup takes 1 to 3 days of engineering time for the initial configuration: build scripts, deployment automation, preview environments for documentation PRs. After that, someone needs to maintain it. Build failures, dependency conflicts, Node version mismatches. These aren't daily problems, but they're recurring ones.

Custom features are where the hidden costs live. Out of the box, Docusaurus gives you search (via Algolia, which requires its own setup), basic versioning, and a default theme. If you need usage analytics, custom authentication, interactive API explorers, or a design that matches your product's brand, you're building those yourself. Each one is a small project. Together, they add up.

The cost nobody tracks: engineering attention. Every hour an engineer spends debugging a broken docs build or updating a deprecated plugin is an hour not spent on the product. It doesn't appear in any line item. It shows up in sprint velocity.

Managed platform costs

Managed platforms charge monthly and include most of what you'd need to build yourself on a self-hosted setup.

• Mintlify: free tier for small projects, paid plans from ~$150/month for team features, custom domains, and analytics

• ReadMe: starts around $99/month, scales with usage and seats. Includes API explorer, metrics dashboard, and user management

• GitBook: free for personal use, team plans from ~$100/month. More wiki-like, good for mixed technical and non-technical teams

• Backstage (Spotify): open source framework but enterprise deployment is a different story. Infrastructure and engineering costs run $170,000 to $500,000+ per year for a production Backstage instance. It's built for internal developer portals at large organizations, not external documentation

What's included in the monthly price varies by platform, but generally: hosting, CDN, search, analytics, versioning, design templates, and support. The things you'd spend weeks building on a self-hosted setup come pre-built.

The TCO comparison that actually matters

A Docusaurus portal on Vercel costs ~$50/month in hosting. Add 10 hours per month of engineering maintenance (conservative for an active portal) at $150 to $250/hour for an engineer's loaded cost, and the real monthly spend is $1,550 to $2,550.

A Mintlify portal costs $150 to $500/month with zero engineering maintenance for core infrastructure. Your team spends time on content, not on builds.

The self-hosted column looks worse than it is if your team already maintains similar infrastructure and the portal is one more app in the stack. It looks much worse than it is if the portal is the only thing your engineers are maintaining outside of the product.

At startup scale with a single product, self-hosted can work cheaply if someone genuinely owns it. At scale with multiple products and a growing docs surface, the engineering time tips the math toward managed.

When to self-host your developer portal

Self-host when you need full design control, have engineering capacity to maintain infrastructure, or face compliance requirements that prevent using third party platforms. The trade-off is flexibility for maintenance burden.

Not every company should self-host. But for the ones where it fits, nothing else gives you the same level of control.

You need customization that managed platforms can't offer

Custom authentication flows for partner-specific portals. Interactive API explorers that go beyond what ReadMe or Mintlify provide out of the box. A white-labeled documentation experience that looks and feels like your product, not like a documentation platform.

If the portal is a core product surface (not a support resource, but something your users interact with daily), self-hosted gives you unlimited room to build exactly what you need. Managed platforms are getting more flexible, but there's still a ceiling. When you hit it, you feel it.

You have engineers who will actually maintain it

This is the filter that matters most. Self-hosting only works if someone owns the infrastructure. Not as a side project. Not as "whoever has time this sprint." A specific person or team accountable for builds, deployments, dependency updates, and uptime.

If you don't have that person, you'll start self-hosted and migrate to managed within 18 months. We've seen this pattern across multiple client engagements. The portal works fine for the first six months while the engineer who set it up is still around. Then they move to a different project, or leave the company, and the docs build starts breaking with nobody to fix it.

Compliance or data residency requires it

Regulated industries (fintech, healthcare, government) sometimes require documentation to live on specific infrastructure or within specific geographic boundaries. Managed platforms are adding region selection, but self-hosted gives you full control over where data lives, how it's encrypted, and who can access the servers.

If your security team needs to audit the documentation hosting infrastructure the same way they audit your application infrastructure, self-hosted is the path of least resistance.

You're building an internal developer portal

Internal portals for internal APIs, internal tooling, and internal knowledge bases often benefit from self-hosting because they integrate with internal auth systems, private networks, and existing CI/CD pipelines. Backstage is the dominant framework here, though the operational cost is significant (see the cost section above).

For external-facing developer documentation, the self-hosted case is about control and customization. For internal documentation, it's about integration with systems that managed platforms can't reach.

LibLab chose Docusaurus for their SDK documentation because the portal needed deep customization and tight integration with their developer tools workflow. A managed platform couldn't accommodate the community-aligned experience they were building. Self-hosted gave them the flexibility to make the portal feel like part of the product, not a bolt-on.

When managed is the better choice

Choose managed when you need a portal live in weeks rather than months, don't have engineering bandwidth to maintain documentation infrastructure, or need built-in features like search, analytics, and versioning without building them yourself.

For most startups and mid-size SaaS companies, managed is the faster, cheaper, and less risky path. Here's when that's especially true.

You need to ship fast

Managed platforms get you from zero to live portal in days. No infrastructure setup, no CI/CD configuration, no custom search implementation. Push your markdown, configure your domain, and the portal is live.

For startups at Seed or Series A where documentation is blocking product adoption right now, that speed difference matters more than any customization advantage. A portal that exists and works beats a self-hosted portal that's still being configured three months from now.

Your engineering team has better things to do

This is the most common reason companies switch from self-hosted to managed. The portal was set up by an engineer who has since moved to another team or left the company. Nobody wants to own the build pipeline. Pull requests to the docs sit unmerged because the CI is broken and fixing it isn't anyone's priority.

Managed platforms eliminate this class of problem entirely. Your engineering team doesn't touch documentation infrastructure because there's no infrastructure to touch. They review content when asked and move on.

If you don't have engineering bandwidth for docs infrastructure, you probably don't have bandwidth to manage the entire documentation program either. That's a separate but related question. Here's waht you need to know about the full cost of in-house documentation vs working with an agency.

You need analytics, search, and versioning without building them

Building Algolia search integration, usage analytics, and multi-version API documentation into a Docusaurus site takes meaningful engineering effort. Managed platforms include all of it. The question is whether building those features yourself creates any unique value, or whether you're just recreating what already exists.

For most companies, the answer is that search is search and analytics are analytics. The value is in what you learn from them, not in having built them yourself.

You have multiple products or APIs

Managing a single Docusaurus site is straightforward. Managing five across different product teams with different release cadences, different API versions, and different audiences is an infrastructure project in itself. Managed platforms handle multi-product documentation natively, with shared navigation, cross-product search, and unified analytics.

Yuno moved from ReadMe to Mintlify and saw a 50%+ increase in product adoption with 15 to 20 minute time to first API call. Nayax unified documentation across 10+ products into a single managed portal that now receives 80,000+ monthly visits with an 80% reduction in support costs. Both were managed platform engagements. The platform handled the infrastructure. The team focused on content quality and information architecture. That's what drove the results. See the full case studies

How the major platforms compare

Self-hosted options (Docusaurus, MkDocs, Nextra, Fumadocs) give you full control and zero licensing costs but require engineering maintenance. Managed options (Mintlify, ReadMe, GitBook) give you speed and built-in features but less customization and a monthly bill.

Here's how they stack up across the criteria that actually affect your decision.

Self-hosted frameworks

Docusaurus is the default choice for self-hosted developer documentation. React-based, MDX support, strong plugin ecosystem, and the largest community of any open source docs framework. If your team knows React, Docusaurus is the obvious starting point. The trade-off is build complexity: larger sites can have slow build times, and the configuration surface area grows with customization.

MkDocs (with the Material theme) is the Python ecosystem's answer. Simpler than Docusaurus, faster to set up, and the Material theme gives it a polish that rivals managed platforms visually. Best for teams already working in Python who want something that feels lightweight and stays out of the way.

Nextra is Next.js-based and tightly integrated with Vercel. Lighter than Docusaurus, faster builds, and a good fit for teams already building on Next.js. The community and plugin ecosystem are smaller, which means more custom work for anything beyond the basics.

Fumadocs is the newest entrant. Also Next.js-based, growing quickly, and opinionated about structure in a way that speeds up initial setup. The trade-off is a smaller community and fewer battle-tested production deployments. Worth watching, but it's earlier in its maturity curve than the others.

Managed platforms

Mintlify has become the go-to for developer-facing documentation where design quality matters. Git-based workflow, strong default templates, fast setup, and increasingly good AI features. Best for external API docs and developer portals where first impressions count. We've migrated several clients to Mintlify from both ReadMe and self-hosted setups.

ReadMe is built for API-first documentation. The built-in API explorer, metrics dashboard, and user management make it strong for companies with complex API products that need usage analytics. It's heavier than Mintlify and more opinionated about structure, which is either a benefit or a constraint depending on your needs.

GitBook sits between a documentation platform and a wiki. Collaborative editing makes it good for mixed teams where non-technical contributors need to write alongside engineers. Best for internal or semi-technical documentation. Less suited for developer-facing API references.

Side-by-side comparison

For a deeper comparison of the managed platforms specifically, including migration considerations and feature breakdowns: GitBook vs ReadMe vs Mintlify: full comparison

The maintenance question that decides it

The right choice depends less on initial setup and more on who maintains the portal 12 months from now. Self-hosted portals quietly accumulate maintenance debt. Managed platforms quietly accumulate lock-in. Pick the cost you'd rather manage.

Both models have a long-term price. The difference is where it shows up.

Self-hosted maintenance debt

Dependency updates. Framework version upgrades. Search index rebuilding. CI/CD pipeline fixes. SSL certificate renewals. CDN configuration changes. None of these are hard individually. Together, they add up to a tax on engineering time that grows as the portal grows.

The portal that "runs itself" after initial setup does not exist. Every self-hosted portal we've worked on requires regular attention. The question is whether that attention comes from a dedicated person or gets squeezed into whatever time is left after product work. When it's the latter, the portal drifts. Pages go stale. Builds break and stay broken for days. The documentation that was supposed to reduce support tickets starts generating them instead.

Managed platform lock-in

Your content is in their system. Migration is possible (most managed platforms support markdown export) but it's never free. You lose custom components, platform-specific features, analytics history, and redirect configurations. The deeper you integrate with a platform's proprietary features, the more it costs to leave.

That said, lock-in is often overstated as a risk. Markdown is portable. API specs are portable. The content itself moves. What doesn't move easily is the platform-specific configuration, design customization, and integrations you've built on top. For most companies, a migration takes 2 to 4 weeks of focused work. It's a real cost, but it's a finite one.

The 18-month test

Ask yourself where your team will be in 18 months. If you'll have a dedicated docs engineer or a documentation team that includes someone comfortable maintaining infrastructure, self-hosted scales well. If documentation will still be a shared responsibility with no clear owner, managed is the safer bet.

The worst outcome is a self-hosted portal with no one maintaining it. It slowly drifts out of date while the team focuses on product work, and by the time anyone notices, the documentation has become a liability instead of an asset. We've inherited portals in this state. The recovery is always more expensive than the managed platform would have been.

Migration is always an option

Starting managed and migrating to self-hosted later is a legitimate strategy. So is the reverse. The cost of migration is real but finite. The cost of choosing wrong and not migrating is ongoing.

Nayax and Yuno both migrated from ReadMe to Mintlify. WriteChoice handled both migrations. The pattern we see: companies rarely regret migrating, they regret waiting.

If you're unsure, start with managed. Ship the portal. Get developers using it. You can always move to self-hosted later when your needs (and your team) outgrow the platform. Don't let "what if we outgrow it" delay a portal that's needed now.

The bottom line

• Self-hosted (Docusaurus, MkDocs, Nextra) costs less in licensing but more in engineering time. The total cost of ownership converges with managed platforms once you factor in maintenance, and it often exceeds it.

• Managed (Mintlify, ReadMe, GitBook) gets you to a live portal faster with less engineering overhead. The trade-off is less customization and platform dependency.

• Self-host when you need deep customization, have dedicated engineering capacity, or face compliance constraints. Go managed when speed matters, engineering bandwidth is limited, or you're managing multiple products.

• The deciding factor isn't the platform. It's whether someone will own the portal 12 months from now. No owner, go managed. Dedicated owner, self-hosted becomes viable.

• Starting on a managed platform and migrating later is a legitimate strategy. Don't let "what if we outgrow it" delay shipping a portal that's needed now.

Not sure which model fits your stack? We've built developer portals on Docusaurus, Mintlify, ReadMe, and GitBook.

Book a call and we'll help you pick the right platform and get it live.