Sourcey
Docs straight from the source.
Sourcey turns OpenAPI, MCP, Doxygen XML, godoc, rustdoc, and Markdown into one static HTML site you own: reference, guides, changelog, roadmap, and llms.txt from the same build, deployable anywhere.
Everything renders at build time: no dashboard, no runtime, no API calls to render your own documentation.
npx sourcey init
Live demo · Documentation · GitHub
Features
- OpenAPI 2.0, 3.0, 3.1, and 3.2: full spec coverage including
QUERYoperations, response summaries, hierarchical tags,deviceAuthorizationOAuth,querystringparameters, and$self-aware refs for multi-document APIs - API reference from OpenAPI: endpoints, parameters, request/response schemas, and auto-generated code samples across 10 supported languages. The default set is cURL, JavaScript, and Python; configure TypeScript, Go, Ruby, Java, PHP, Rust, and C# when you want them
- MCP server documentation: tools, resources, prompts rendered as browsable reference with JSON-RPC, TypeScript, and Python code samples. Color-coded method types, annotation badges, connection config cards
- Rich guides: markdown pages with steps, cards, accordions, syntax-highlighted code blocks, and prose alongside your API reference
- One-time migration: convert an existing Astro or MkDocs documentation project to native Sourcey Markdown and configuration, with a dry-run diff and checks for routes, fragments, content and media. Migration guide
- Product story pages: changelog, roadmap pages, examples, reference material, search, and portable context exports in one source-owned site
- C++ and Doxygen: feed Doxygen XML output, get modern searchable API docs with exact member search, source links, templates, qualifiers, examples, inherited members, and relationship sections. No new parser, no four-tool Breathe/Exhale/Sphinx pipeline
- Go and godoc: native package documentation extracted from Go source via the toolchain. Render Go modules as Sourcey tabs, generate standalone static Go docs sites, or commit
godoc.jsonsnapshots for JS-only docs hosts. No Doxygen detour - Rust and rustdoc: native API documentation from nightly rustdoc JSON, with doctests as a first-class extracted view. URL-encoded parametric impl anchors for deep-link parity with doc.rust-lang.org. Snapshot mode lets CI build on stable Rust toolchains. Aggregated doctests index across the workspace
- Readable reference for agents: Markdown for pages, API operations and schemas, plus
documents.json,llms.txtandllms-full.txt. Code examples retain their formatting - API and agent discovery: opt into public OpenAPI bundles, ARD manifests and RFC 9727 API catalogs. Mounted docs keep the host's root manifest under its owner's control. Configuration
Install
Sourcey CLI
The full Sourcey binary handles OpenAPI, MCP, Doxygen, godoc, rustdoc, and Markdown sources. Existing Astro and MkDocs projects have one-time converters.
Then sourcey init to scaffold a new project, or sourcey build against an existing one. See docs/install.md for full Docker invocations (init / dev / build), the --host flag for containerized dev, Linuxbrew notes, and Nix profile install.
Standalone Go docs generator
For Go-only consumers without a JavaScript toolchain, sourcey-godoc ships as a separate native binary. It produces static Go docs sites or portable godoc.json snapshots.
Rust snapshot converter
The rustdoc() adapter consumes nightly rustdoc JSON through the sourcey companion crate and its sourcey-rustdoc converter, so CI can build Rust API docs from a committed snapshot on a stable toolchain. See docs/adapters/rustdoc.md.
Quick start
# Scaffold a project (detects OpenAPI specs and Doxyfiles)
npx sourcey init
# Dev server with hot reload
sourcey dev
# Build static HTML to dist/
sourcey build
# Quick build from a single OpenAPI spec
sourcey build api.yaml -o dist/
In CI, the sourcey/build-docs GitHub Action runs the build and deploys to GitHub Pages; see deploying.
Astro integration
Astro sites can mount Sourcey directly instead of running a separate docs CI job. The integration reads the same sourcey.config.ts, derives Sourcey's public siteUrl and baseUrl from Astro's site/base plus routeBase, serves docs in Astro dev, and writes docs into Astro's final build output.
// astro.config.ts
import { defineConfig } from "astro/config";
import sourcey from "sourcey/astro";
export default defineConfig({
site: "https://sourcey.com",
integrations: [
sourcey({
config: "./sourcey.config.ts",
routeBase: "/docs",
}),
],
});
You can also share an imported config object when you want one config module to feed both the CLI and Astro:
import { defineConfig } from "astro/config";
import sourcey from "sourcey/astro";
import docs from "./sourcey.config";
export default defineConfig({
site: "https://sourcey.com",
integrations: [sourcey({ config: docs, configDir: ".", routeBase: "/docs" })],
});
To give the mount root to an Astro page of your own, such as a product page at /docs above the documentation, set landingPage: false. Sourcey leaves an automatic root copy out of the build and lets Astro serve its own landing page. An authored index.md is still a real documentation route; give it a separate slug when the host owns that address.
Configuration
Create sourcey.config.ts in your project root:
import { defineConfig, openapi } from "sourcey";
export default defineConfig({
name: "My API",
navigation: {
tabs: [{ tab: "API Reference", source: openapi("./openapi.yaml") }],
},
});
Each tab has one source, usually created with markdown(), openapi(), mcp(), doxygen(), godoc(), or rustdoc(). Pages are referenced by slug (e.g. "quickstart" resolves to quickstart.md). See docs/configuration.md for theme, navbar, footer, logo, and full tab options.
Go documentation (godoc)
Render Go package docs as a tab inside your Sourcey site, branded and styled with the rest of your documentation. Native toolchain extraction (go list + go/parser + go/doc) feeds the same renderer as your OpenAPI, MCP, and Markdown tabs, so signatures, examples from *_test.go, and source links sit alongside your guides instead of bouncing readers to pkg.go.dev.
Live: scafld's Go API reference →
{ tab: "Go API", source: godoc(".") }
The shorthand expands to { module: ".", packages: ["./..."], mode: "auto", includeTests: true }. Live mode uses the host Go toolchain; snapshot mode reads a committed godoc.json and needs no Go on the build host. See docs/configuration.md for packages, mode, goEnv, sourceBasePath, and includeUnexported.
Markdown components
Guides support rich components in standard markdown:
<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>
Theme
All visual configuration lives under theme. theme.name selects the complete renderer; colors, fonts, layout dimensions, and custom CSS apply on top:
theme: {
name: "api-first",
colors: { primary: "#f59e0b", light: "#fbbf24", dark: "#d97706" },
fonts: { sans: "'Lexend', sans-serif", mono: "'Fira Code', monospace" },
layout: { sidebar: "16rem", content: "48rem" },
css: ["./brand.css"],
}
Themes control the complete layout structure: "default" (sidebar + TOC), "minimal" (single centered column), "api-first" (full width, with each API and MCP operation's examples beside it), and "reader" (editorial specification reader). Shared brand settings apply on top. Theme-specific options are only interpreted by the selected theme.
CLI
sourcey dev Dev server (reads sourcey.config.ts)
sourcey build Build site (reads sourcey.config.ts)
sourcey build api.yaml Quick build from a single spec
sourcey validate api.yaml Validate a spec file
sourcey godoc --out godoc.json Snapshot a Go module's docs to JSON
sourcey-godoc generate --out site Standalone Go CLI for static godoc sites
Run sourcey <command> --help for flags.
Development
git clone https://github.com/sourcey/sourcey.git
cd sourcey && npm install
npm run build && npm test
cd go/sourcey-godoc && go test ./... && go vet ./...
# Run the in-repo docs site against your working copy
cd docs && npx tsx ../src/cli.ts dev
License
Commercial licensing available; contact sourcey.com.
