← Code
sourcey

sourcey

Open source documentation engine for OpenAPI, MCP servers, Doxygen and Markdown guides.

Website → GitHub → Demo → Docs →
TypeScriptPreactOpenAPIMCPViteShiki

Sourcey is a documentation engine that takes an OpenAPI spec, an MCP server snapshot, or a Doxygen XML directory, combines them with markdown guides, and produces a complete documentation site. Static HTML output. No framework shipped to the browser. No runtime. Deploy to GitHub Pages, Vercel, S3, your own server.

The config is TypeScript:

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",
      },
      {
        tab: "MCP Server",
        mcp: "./mcp.json",
      },
    ],
  },
});

Full type safety, dynamic values, imports. defineConfig() gives you autocomplete and validation before you even run a build.

The pipeline

Most documentation tools parse a spec and render it in one pass. Sourcey treats spec processing as a pipeline with distinct stages:

  OpenAPI   -->  LoadedSpec --> ParsedSpec --> OpenAPI 3.x --> NormalizedSpec --> HTML
  MCP JSON  -->  McpSpec    --------------------------------> NormalizedSpec --> HTML
  Doxygen   -->  DoxygenXML --------------------------------> NormalizedSpec --> HTML
  Markdown  --------------------------------------------------> HTML

  Each path converges at NormalizedSpec: a format-agnostic internal representation
  that the renderer, search indexer, and llms.txt generator all consume.

The 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 specs into a format-agnostic internal representation. MCP and Doxygen have their own normalizers that produce the same output structure. The renderer turns everything 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.

MCP server documentation

Sourcey renders MCP servers as first-class reference documentation. Point it at an mcp.json snapshot (output from mcp-parser) and it generates browsable docs with the same design language as your REST API reference. Tools get purple method pills, resources get green, prompts get blue. Annotation badges surface hints like read-only, destructive, and idempotent at a glance. Connection config cards show developers exactly how to wire the server into Claude, Cursor, or any MCP client; copy the JSON and go.

Code samples generate automatically in JSON-RPC, TypeScript SDK, and Python SDK. Tool calls include arguments, resource reads include URI templates, prompt invocations include parameters. The same pipeline that handles OpenAPI normalization handles MCP; downstream rendering, search, navigation, and theming all work without special cases.

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>
  <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.

Code samples

Auto-generated at build time. OpenAPI gets 10 languages: cURL, JavaScript, TypeScript, Python, Go, Ruby, Java, PHP, Rust, and C#. MCP gets JSON-RPC, TypeScript SDK, and Python SDK. Configurable via codeSamples in sourcey.config.ts; defaults to cURL, JavaScript, and Python for REST, all three for MCP.

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 [email protected]). Each language gets its own icon in the switcher dropdown (Simple Icons, CC0). All baked into the HTML. Zero client-side overhead.

llms.txt

Every sourcey build generates llms.txt and llms-full.txt alongside your HTML. The same content that serves developers through the browser serves AI agents through machine-readable indexes. OpenAPI endpoints, MCP tools, resources, prompts; all included with proper labels and descriptions. One build, two audiences.

Client-side interactivity

All interactivity is vanilla JavaScript; six small modules concatenated in dependency order. No bundler, no framework.

  • Search: / or Ctrl+K opens a search dialog that filters endpoints and models instantly. Results navigate with arrow keys and Enter.
  • Dark mode: Toggle 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: IntersectionObserver highlights 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.

C++ and Doxygen

Sourcey uses moxygen as a library to consume Doxygen XML directly and produce modern, searchable, themeable documentation. Add a doxygen tab to your sourcey.config.ts, point it at your XML output directory, and your C++ API reference renders natively alongside your markdown guides.

{
  tab: "API Reference",
  doxygen: { xml: "./doxygen/xml", language: "cpp" },
}

Keep your Doxyfile. Keep your comment style. No new parser to trust, no new comment syntax to learn, no four-tool pipeline to configure. icey’s own C++ docs run through this pipeline.

Open source

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. Documentation is infrastructure; it should be owned, not rented.