Self-hosted documentation gives you control. Hosted documentation removes operational responsibility. Neither model is automatically cheaper or better.
The decision depends on whether documentation infrastructure is a strategic product your engineers want to own or recurring work they want a vendor to absorb.
The Decision in One Table
| Question | Hosted documentation | Self-hosted documentation |
|---|---|---|
| Initial setup | Faster and opinionated | Flexible but engineering-led |
| Design control | Limited by product and theme | Full framework-level control |
| Hosting and upgrades | Vendor responsibility | Team responsibility |
| Authoring | Usually browser plus Git | Usually Git and local tools |
| Search and analytics | Often integrated | Selected and integrated separately |
| Agent-facing outputs | Product-dependent | Build what you need |
| Cash cost | Recurring software fee | Often low infrastructure spend |
| Labor cost | Lower operating burden | Can be the largest cost |
| Portability | Depends on export and source ownership | High when content is repository-owned |
Choose Self-Hosted When Control Is the Point
Frameworks such as Docusaurus, Fumadocs, and Starlight are compelling when the docs site is part of the product frontend. They let engineers control components, routes, build behavior, data sources, and deployment.
Self-hosting is strongest when:
- the company already runs the required stack
- custom product integration matters
- source ownership and portability are mandatory
- the team can maintain dependencies and CI
- a developer actively owns documentation infrastructure
- vendor constraints would block a core requirement
Do not choose self-hosting only because the framework license is free. Estimate setup and monthly labor first.
Choose Hosted When the Operation Is the Problem
A hosted platform can bundle the site runtime, editor, search, previews, redirects, analytics, machine-readable outputs, and support. It is strongest when documentation needs to ship quickly but no one wants to become the infrastructure owner.
Hosted documentation is usually better when:
- one or two people manage the entire docs program
- engineering time should stay on the product
- non-engineers need a browser editor
- fast publishing and migration support matter
- performance and uptime need a clear owner
- agent-facing delivery should work without custom integrations
The tradeoff is product constraint. Confirm exports, Git sync, custom-domain support, redirects, traffic limits, and component compatibility before buying.
Compare Operating Models, Not Feature Counts
Ask these five questions:
- Who responds when the build breaks? If no one owns that work, self-hosting creates an invisible queue.
- How custom must the public experience be? A deeply integrated portal may need framework control.
- Where do contributors work? Browser editors help mixed teams; Git helps engineering-led teams.
- What must agents consume? HTML alone may not be enough. Check Markdown,
llms.txt, API schemas, and MCP. - Can we leave? Content export, URL ownership, redirects, and source control determine switching cost.
Model the First Year
Include:
- one-time migration and setup hours
- monthly maintenance hours
- loaded engineering rate
- hosting and bandwidth
- search, analytics, monitoring, and forms
- localization or versioning services
- vendor subscription
Then compare outcomes, not only expense. A more expensive platform can still be better if it increases activation or removes enough recurring work.
Use the documentation hosting cost calculator for your assumptions. If you choose to switch platforms, follow the migration checklist before changing DNS.