Capsa: Stop Renting Your Documentation

Today I’m open-sourcing Capsa, a self-hosted documentation platform. You write MDX; it renders a polished docs site — prerendered static HTML, a ⌘K command-palette search, a themed OpenAPI reference, social cards, AI-friendly exports — and it deploys to Cloudflare Pages (or any static host) for free. It’s a Vite + React + Tamagui app you fully own and can edit.

Why I Built This

I’m a believer in documentation — not the compliance kind that gets written once and rots, but the useful kind. Runbooks for problems you’ve already solved. The “here’s how you actually get this running” page that saves a new person their first two days. The record of why a decision was made, so the next engineer — often the next version of me, six months later — doesn’t have to reverse-engineer the reasoning from the code.

I was already building an internal Markdown docs site for exactly this. Then I went to pick a “real” platform for the products I’m about to ship, priced the options, and ran into the same wall everyone hits.

Documentation tools make you choose two of three: own your stack, don’t maintain the infrastructure, don’t pay rent. Mintlify gives you the last two — managed and polished — but you rent it, and your content lives in their cloud. Docusaurus and Nextra give you the first two — own it, host it free — but you maintain the thing, assemble search and OpenAPI and social cards yourself, and fight the theme system. I wanted all three. Nothing was offering all three.

So I built it.

Why “Capsa”

A capsa was the cylindrical case a Roman carried their scrolls in. This one holds yours. All of my products follow a Roman theme, and this one was almost too on the nose: a container you own, that protects the documents you put inside it, that you carry with you rather than leave in someone else’s library.

The Cost of Renting

Let me be fair to Mintlify first, because it’s genuinely good: the editing experience is polished, the agent and assistant features are real, and a serious slice of recent YC batches ship docs on it. If you want a managed platform with a web editor your non-technical teammates can use, it’s a strong choice.

But I priced the plan I’d actually have needed, and when I evaluated it the tier ran about $450/month — roughly $5,000 a year. The features gating that price were things like webhooks, websockets, a developer API, platform and agent analytics, advanced insights, enterprise file types, and multi-repo deployments. (Mintlify has since moved toward a credits-based model, so check current pricing — my point is the class of cost, not the exact SKU.)

Here’s the honest accounting for my situation:

I’m not saying those features are worthless. A managed solution is a real thing to pay for, and if you’re a team without the appetite to run your own site, $5k a year is nothing against an engineer’s time. But for what is fundamentally a Markdown renderer plus a host, I couldn’t justify it.

And there’s a deeper reason than money. If someone else hosts your docs, you’re renting your documentation. Your content, your search index, your URLs, your theme — all sitting inside a vendor you’d have to migrate off of if the pricing or the product changed. Documentation is one of the few assets that should outlive every tool you used to write it. I didn’t want mine living on someone else’s shelf.

What I Wanted

Concretely: a docs platform that’s configurable and personalized, easy to set up and manage, with no vendor lock-in, consistent with the stack I already use (Tamagui), and with first-class OpenAPI support — because the products I’m shipping have APIs, and I didn’t want the API reference to be a bolted-on afterthought that looks nothing like the rest of the site.

What It Does

Capsa renders MDX into a real docs site. Drop a Markdown file into a folder under content/ and the path becomes the route — no manifest to update, no route to register. The shipped config auto-includes each content folder in the sidebar, so a new page shows up without touching navigation.ts; you edit that file only when you want explicit ordering or nesting.

---
title: Hello
description: My first Capsa page.
---

# Hello

This file is served at **/docs/guides/hello** — no config, no route to register.

Drop a content/home.mdx and / becomes a proper landing page with hero, feature-grid, and CTA components; delete it and / redirects into the docs.

Point it at an OpenAPI spec and you get an interactive API explorer, themed to match the rest of the site rather than looking like a different product entirely.

How It Works

The stack is Vite, React 19, TypeScript, Tamagui, MDX, Scalar for the OpenAPI reference, Pagefind for search, and Satori for social cards. A few decisions I’m actually happy with:

Unified theming across docs and the API reference. This is the one I care about most. Most setups render your prose in one design system and your OpenAPI reference in whatever the API tool ships with, and the seam is obvious. In Capsa the Scalar reference is themed from the same tokens as everything else — four styles times light/dark, all brandable — so the API docs feel like part of the site, not a tab that teleports you to a different website.

Static ⌘K search with no search service. Search is powered by Pagefind over the prerendered pages: a keyboard-first command palette, typo-tolerant, fully static, with a build-time JSON index as a fallback. No Algolia subscription, no search backend to run. For what should be a simple functioning website, I didn’t want a SaaS dependency just so people can find a page.

Prerendered (SSG) that hydrates. Every doc ships as real static HTML — the full article and crawlable nav links — then hydrates into the SPA. That means it’s SEO-complete out of the box (titles, descriptions, OpenGraph, canonical URLs, sitemap) instead of the blank-shell problem you get from a pure client-side app. One pnpm build runs the whole pipeline: SSR bundle, then a prerender pass that writes static HTML, a social-card PNG per page, and the search index.

And it deploys to Cloudflare Pages for free. Build command, output directory, done.

Docs for a Second Audience

Here’s the part I think matters most going forward. Your documentation now has two audiences: the human reading it, and the model the human is about to paste it into.

Capsa treats that as first-class. It generates an llms.txt, every page has a “Copy as Markdown” action, and there’s an “Open in ChatGPT/Claude” button that hands the page straight to an assistant. The code comment on that feature says it plainly: zero backend, zero token cost — the user’s own assistant does the work.

To be precise about what this is: it’s not SEO. SEO is for search-engine crawlers. This is AI discoverability — making your docs trivially ingestible by an LLM, because more and more people don’t read the docs and then act; they feed the docs to an agent and ask it to act. If your documentation is a pile of client-rendered HTML an agent can’t cleanly read, you’ve made yourself invisible to the way a growing share of your users actually work.

How Capsa Fits Among Other Tools

Capsa isn’t the only way to publish docs. It fits a specific niche:

Capsa’s niche: self-hosted, free to run, OpenAPI and search built in, themed as one coherent site, and built for both human and AI readers. If you want a managed dashboard and a web editor, that’s a different set of trade-offs.

When NOT to Use Capsa

Capsa is young, and I’m not going to pretend otherwise. Here’s who should pick something else:

• You have non-technical contributors. There’s no WYSIWYG editor. You write Markdown and commit it; the “Edit this page” button opens the source on GitHub, and a push auto-deploys. If your PMs or support team need a visual editor, use Mintlify or GitBook.
• You need translated docs. There’s no i18n / localization layer. (The language switcher in Capsa is for code samples — Go vs. Python vs. curl — not human languages.) Docusaurus has mature i18n; Capsa doesn’t have it at all yet.
• You need reader-facing versioned doc sets. Showing readers v1/v2/v3 of your docs isn’t built yet. Git holds the history, but that’s not the same as a version switcher. It’s a feature I can add; today it’s not there.
• You want a managed platform with an SLA and support. There’s no one to call. You own uptime, migrations, and breakage. That’s the flip side of owning it.
• You want the safety of an established player. Docusaurus has a massive community, years of plugins, and a StackOverflow answer for every problem. Capsa is new and, right now, effectively maintained by me. The mitigation is that it’s Apache-2.0: if I get hit by a bus, you have the whole thing and can fork it. But go in with eyes open.

Try It

Use the repo as a GitHub template, or clone it:

pnpm install
pnpm dev        # http://localhost:3001
pnpm build      # SSR bundle -> prerendered client build -> dist

Add a page by dropping a Markdown file into a folder under content/; the path becomes the route and it appears in the sidebar automatically. A bare deploy needs zero configuration — auth is opt-in, and a fresh clone runs public by default. Deploy to Cloudflare Pages with a build command of pnpm install && pnpm build and an output directory of dist.

The full docs (this repo is itself a Capsa site) are at capsa.romans.dev, and the code is on GitHub. If you hit rough edges, Issues is the right place; if you want versioned docs or i18n, that’s exactly the kind of thing worth opening a request for.

Own your documentation. Clone the template, write some Markdown, and ship a docs site you don’t have to rent.

Capsa is part of SID Technologies — small, focused tools, Roman names. The thread that runs through them: build the thing you needed last week, ship it open-source, write down what you learned.