The API documentation space has been captured by SaaS platforms selling you your own content back on a subscription. Mintlify charges $150/month to host markdown files. GitBook locks your docs behind their editor. ReadMe wants API calls to render your own documentation. Fern generates SDKs but ties you to their cloud. Stoplight is enterprise middleware wearing a docs-platform disguise. Every one of them is a SaaS trap dressed up as a developer tool, and every one of them can change their pricing, their terms, or their product direction whenever they please. Your documentation is your product’s front door, and you’ve handed the keys to a landlord.
We built Sourcey because we needed API docs that looked as good as Stripe’s, generated from a spec file, deployed wherever we wanted, and didn’t require a monthly payment to a platform that could disappear or pivot at any moment. The existing open source options were either ugly (Swagger UI looks like a government form) or shipped an entire React runtime to render what should be static HTML (Redoc). So we started from scratch.
Point Sourcey at an OpenAPI spec, add markdown guides alongside it, and you get a complete documentation site. Static HTML output. No framework shipped to the browser. No runtime. No vendor lock-in. Deploy to GitHub Pages, Vercel, S3, your own server. It’s your content, on your infrastructure, under your control.
Sourcey vs alternatives
| Sourcey | Mintlify | GitBook | Fern | Redocly | VitePress | |
|---|---|---|---|---|---|---|
| OpenAPI reference | Native | Native | No | Native | Native | Plugin |
| Markdown guides | Native | Native | Native | Native | Native | Native |
| Static output you own | Yes | No | No | No | Yes | Yes |
| Zero JS shipped | Yes | No | No | No | No | No (Vue SPA) |
| TypeScript config | Yes | JSON | GUI | YAML | YAML | TS |
| Hot reload dev server | Vite SSR | Cloud | Cloud | Cloud | Webpack | Vite SPA |
| Rich components | Yes | Yes | Limited | Yes | No | Vue |
| Theme presets | Yes | No | No | No | No | Yes |
| Self-hosted | Yes | No | No | No | Yes | Yes |
| Pricing | Free / AGPL | $150+/mo | Free / paid | Paid | Free / paid | Free |
The docs platform problem
Most documentation tools are either generators or platforms, never both. Generators handle API reference but can’t do prose guides. Platforms do everything but lock you into their hosting and editor. The result is that most teams end up running two systems: one for API reference, another for guides, tutorials, and conceptual docs. Two designs, two deployment pipelines, two sets of problems.
Sourcey treats API reference and markdown guides as the same problem. Configure your navigation in sourcey.config.ts; each tab is either an OpenAPI spec or a collection of markdown pages. They share the same design, the same nav, the same build. One tool, one output.
import { defineConfig } from "sourcey";
export default defineConfig({
name: "Cheese Store",
theme: {
preset: "default", // "default", "minimal", or "api-first"
colors: { primary: "#f59e0b" },
fonts: { sans: "'Lexend', sans-serif" },
},
navigation: {
tabs: [
{
tab: "Documentation",
groups: [
{ group: "Getting Started", pages: ["introduction", "quickstart"] },
{ group: "Guides", pages: ["concepts", "webhooks"] },
],
},
{
tab: "API Reference",
openapi: "./openapi.yaml",
},
],
},
});The config is TypeScript, not JSON. Full type safety, dynamic values, imports; whatever you need. defineConfig() gives you autocomplete and validation before you even run a build.
Theming
Everything visual lives under theme. Colors, fonts, layout dimensions, and a preset that controls the page structure.
Three presets ship out of the box. Default gives you sidebar navigation with a right-side table of contents for prose and sticky code panels for API reference. Minimal strips the sidebar entirely; single centered column, clean for landing pages and changelogs. Api-first is the Stripe layout: sidebar, content, and persistent example panels that appear at a smaller breakpoint so the code is always visible alongside the docs.
The preset controls structure. Colors, fonts, and layout dimensions apply on top of any preset. For anything the config doesn’t cover, theme.css takes an array of CSS file paths loaded after the theme; full override capability without forking.
theme: {
preset: "api-first",
colors: { primary: "#3b82f6", light: "#60a5fa", dark: "#2563eb" },
fonts: { sans: "'Inter', sans-serif", mono: "'Fira Code', monospace" },
layout: { sidebar: "16rem", content: "48rem" },
css: ["./brand.css"],
}Markdown components
Guides support rich components in standard markdown. Steps, cards, accordions; the same building blocks Mintlify charges you for, without the SaaS dependency.
<Steps>
<Step title="Install">Run `npm install sourcey`</Step>
<Step title="Configure">Create `sourcey.config.ts`</Step>
<Step title="Build">Run `sourcey build`</Step>
</Steps>
<CardGroup cols={2}>
<Card title="API Reference" icon="book" href="/api">Full endpoint docs</Card>
<Card title="Guides" icon="map" href="/docs">Step-by-step tutorials</Card>
</CardGroup>
<AccordionGroup>
<Accordion title="How does auth work?">We use API keys and OAuth2.</Accordion>
</AccordionGroup>Dev server
Vite-powered SSR hot reload. Edit a component, a style, your spec, or your markdown; changes appear instantly. No manual rebuild, no full page refresh.
The pipeline
Most documentation tools parse your spec and render it in one messy pass. Sourcey treats spec processing as a pipeline with distinct stages, each handling one concern:
YAML/JSON --> LoadedSpec --> ParsedSpec --> OpenAPI 3.x --> NormalizedSpec --> HTML
| | | | | |
loader parser converter normalizer renderer builder
path/URL dereference 2.0 -> 3.0 tags, ops Preact SSG css + js
resolve $ref (passthrough schemas renderToString + assets
from file dir if 3.x) securityThe loader accepts file paths, URLs, JSON, or YAML. The parser dereferences all $ref pointers. The converter handles Swagger 2.0 by converting to OpenAPI 3.0. The normalizer transforms raw OpenAPI into a format-agnostic internal representation. The renderer turns that into HTML. Each stage is independently testable and replaceable.
Dereferencing happens before conversion; deliberately. $ref pointers need to resolve against the original file’s directory structure. A relative reference like ./schemas.yaml#/Pet only makes sense from the source file’s location. Convert first and you lose that context.
Code samples
Auto-generated examples in 10 languages at build time: cURL, JavaScript, TypeScript, Python, Go, Ruby, Java, PHP, Rust, and C#. Configurable via codeSamples in sourcey.config.ts; defaults to cURL, JavaScript, and Python. The generator recurses through schemas with cycle detection: example > default > first enum > const > type-specific fallback. String formats produce intelligent defaults (date-time gives an ISO timestamp, email gives user@example.com). Each language gets its own icon in the switcher dropdown (Simple Icons, CC0). All baked into the HTML. Zero client-side overhead.
Client-side interactivity
All interactivity is vanilla JavaScript; six small modules concatenated in dependency order. No bundler, no framework.
- Search:
/orCtrl+Kopens a search dialog that filters endpoints and models instantly. Results navigate with arrow keys and Enter. - Dark mode: Toggle button that respects system preference and persists via localStorage. The entire theme switches; not just the code panel.
- Synced language tabs: Switch from curl to Python in one example and every example on the page follows. Selection persists across page loads.
- Scroll tracking:
IntersectionObserverhighlights the current section in the sidebar as you scroll. - Clipboard copy: One-click copy on code blocks with visual feedback.
- Sidebar: Drawer toggle with close on outside click or Escape.
Why open source matters here
We’ve watched the docs space consolidate into SaaS platforms that charge per-seat for what amounts to static site generation. Every year there’s a new one, and every year it’s the same pitch: “beautiful docs, zero effort.” The effort isn’t zero; it’s deferred. You pay when you need to migrate, when the pricing changes, when the platform decides your use case isn’t profitable enough to support.
Documentation is infrastructure. It should be owned, not rented. Sourcey is AGPL-3.0; free to use, self-host, and modify. If you run it as a hosted service, you open-source your stack. The incentive structure is deliberate: we want more open documentation tools, not more walled gardens.