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

!Sourcey

Live demo · Documentation · GitHub

Features

• OpenAPI 2.0, 3.0, 3.1, and 3.2: full spec coverage including QUERY operations, response summaries, hierarchical tags, deviceAuthorization OAuth, querystring parameters, 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.json snapshots 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.txt and llms-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
• Docs over MCP: the optional sourcey-docs-mcp package searches and reads a built documentation directory. Its SDK stays out of the generator and browser bundle
• TypeScript config: sourcey.config.ts with defineConfig() autocomplete; theme, navbar, CTA buttons, footer
• Themes: default (sidebar + TOC), minimal (single column), api-first (full width, with examples beside each API operation), and reader (editorial specification); colors, fonts, layout dimensions, and custom CSS on top
• Vite dev server: SSR hot reload on every component and CSS change; spec and markdown changes trigger instant refresh
• Dark mode: semantic design tokens, light/dark logo variants, localStorage persistence
• Client-side search: instant fuzzy search across all pages and API operations; Cmd+K
• Static HTML output: no framework runtime, no vendor lock-in. Deploy to GitHub Pages, Vercel, Netlify, S3, anywhere
• Open source: AGPL-3.0. Self-host, fork, extend. Your docs, your infrastructure

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.

| Path | Command | Requires | | -------- | ---------------------------------------------- | ---------------------------- | | npm | npm install -g sourcey | Node 22.22.2+, 24.15+ or 26+ | | Homebrew | brew tap sourcey/tap && brew install sourcey | macOS / Linuxbrew | | Docker | docker run -v "$PWD":/docs sourcey/sourcey | Docker | | Nix | nix run github:sourcey/sourcey | Nix (flakes) |

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

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 --help for flags.

Agent skill

The Sourcey skill teaches a coding agent to start a documentation site, migrate one from Docusaurus, MkDocs, Mintlify or Astro, shape its API and MCP references, and review it as a reader before it ships. It is in the npm package at node_modules/sourcey/skills/sourcey, and this repository packages it as the sourcey-docs plugin for each agent host:

# Claude Code
/plugin marketplace add sourcey/sourcey
/plugin install sourcey-docs@sourcey
Gemini CLI
gemini extensions install https://github.com/sourcey/sourcey

Cursor, Grok Build and ChatGPT/Codex read the manifests in .cursor-plugin/, .grok-plugin/ and plugin.json. Sourcey's startup offers have their own plugin, sourcey; this one is for the documentation generator.

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

AGPL-3.0.

Commercial licensing available; contact sourcey.com.