Sourcey: OpenAPI, MCP, Doxygen and godoc into one static HTML site

The documentation drift Sourcey is built to remove

Most API documentation problems are not writing problems. They are duplication problems. The spec says one thing, the hand-written reference page says another, and the changelog says a third. Sourcey's answer is to make the spec the source of truth and render everything else from it in a single build. The README describes the output as "one static HTML site you own: reference, guides, changelog, roadmap, and llms.txt from the same build".

The audience is narrow and identifiable. It is teams that already keep an OpenAPI document, a Doxyfile, a Go module or a rustdoc JSON snapshot in version control and want the published docs generated from those artifacts rather than maintained beside them. It is also teams that have been pushed toward a hosted documentation platform and would rather not have their reference pages depend on someone else's runtime. The README is explicit on that point: everything renders at build time, with "no dashboard, no runtime, no API calls to render your own documentation".

That framing has a cost the README does not dwell on. If your documentation is written by people who will not touch a repository, this is the wrong shape of tool. There is no browser editor described anywhere in the README.

How the build pipeline turns specs into pages

Sourcey is a Node package with a `sourcey` binary pointing at `dist/cli.js`, and `package.json` declares `"engines": { "node": ">=20" }`. The CLI has three verbs in the quick start: `init`, `dev` and `build`. Configuration lives in `sourcey.config.ts` and uses a `defineConfig()` helper for autocomplete, which the README lists under features alongside theme, navbar, CTA buttons and footer.

The source side is a set of adapters. OpenAPI 2.0, 3.0, 3.1 and 3.2 are handled in-process, including `QUERY` operations, hierarchical tags, `deviceAuthorization` OAuth, `querystring` parameters and `$self`-aware refs for multi-document APIs. MCP servers are rendered as browsable reference for tools, resources and prompts with JSON-RPC, TypeScript and Python samples. Doxygen XML is consumed directly, which the README contrasts with the "four-tool Breathe/Exhale/Sphinx pipeline". Go documentation is extracted from source through the toolchain rather than through Doxygen. Rust documentation comes from nightly rustdoc JSON.

The output is static HTML in `dist/` with no framework runtime. Alongside the HTML, the build emits `llms.txt` and `llms-full.txt` as "alternate views of the same documentation graph", which is a sensible byproduct of already having a structured graph in memory. Theme presets are default (sidebar plus table of contents), minimal (single column) and api-first (three column, Stripe-style).

The interesting architectural choice is what ships inside the npm package. The build script copies `go/sourcey-godoc` and `rust/sourcey-rustdoc` into `dist/core/`, and deletes any pre-built binaries before doing so. Sourcey is not reimplementing a Go parser or a Rust parser in TypeScript; it is vendoring the real toolchain-adjacent tooling into the package and invoking it.

Installing Sourcey and building a first site

The README gives four installation paths for the full CLI. Node 20 or newer is the floor for the npm route, and the Docker image is `node:20-alpine` with the CLI installed globally at build time.

npm install -g sourcey

Homebrew, Docker and Nix are the other three. The Docker invocation mounts the working directory at `/docs`, which is where the image's `WORKDIR` points and where the `build` command runs by default.

docker run -v "$PWD":/docs sourcey/sourcey

For a new project, `init` scaffolds the configuration and, according to the README, detects OpenAPI specs and Doxyfiles present in the directory.

npx sourcey init

From there the two commands you will actually live in are the dev server and the build. The dev server is a Vite server with SSR hot reload; the README states that spec and markdown changes trigger an instant refresh.

sourcey dev
sourcey build

If you already have a spec and do not want a scaffolded project, the README shows a single-spec build with an explicit output directory.

sourcey build api.yaml -o dist/

The result is a `dist/` directory of static files. Deploy targets named in the README are GitHub Pages, Vercel, Netlify and S3, and there is a `sourcey/build-docs` GitHub Action that runs the build and deploys to GitHub Pages. Astro sites can mount the integration through the `sourcey/astro` export instead of running a separate docs job.

Where Sourcey stops being the right tool

The build-time model is the limitation, not a side effect of it. Anything that needs to change without a rebuild cannot change. There is no runtime API serving your docs, so per-request personalization, live try-it-out calls against a real backend, or version selection that resolves at request time are outside what the README describes. If your reference pages must reflect a schema that changes hourly, you are signing up for a build on every change.

The adapter set is also a boundary. OpenAPI, MCP, Doxygen XML, godoc, rustdoc and Markdown are the inputs named in the README. A project documented in JSDoc, TypeDoc, JavaDoc HTML or a proprietary schema format has no listed path in. The README does not describe a generic plugin interface for adding one, and the absence of that in the README is worth taking at face value rather than assuming it exists.

Two narrower caveats sit inside the feature list. The default code sample languages are cURL, JavaScript and Python; TypeScript, Go, Ruby, Java, PHP, Rust and C# are opt-in, so a polyglot audience needs configuration before the samples look right. And the MkDocs import reads `mkdocs.yml` for `docs_dir` and `nav` so an existing MkDocs markdown site can render without hand-copying the sidebar. That is an import of content and navigation, and the README describes nothing about MkDocs themes or plugins carrying over.

Finally, the Rust path consumes nightly rustdoc JSON. The README notes that snapshot mode lets CI build on stable toolchains, which is the mitigation, but it means a committed snapshot artifact is part of your workflow rather than a live extraction.

Sourcey against Docusaurus and MkDocs

The honest comparison is with the static site generators people already use for docs, because the deployment story is identical and the difference is upstream.

Docusaurus and MkDocs are content-first. You write markdown, you configure a sidebar, you get a site. An API reference page is something you generate separately and paste in, or wire up through a plugin that renders the spec into a page. Sourcey inverts that: the reference is the primary artifact, and markdown guides are one of several inputs into the same build. The README's phrase for the guide side is "markdown pages with steps, cards, accordions, syntax-highlighted code blocks, and prose alongside your API reference". The prose sits beside the generated reference rather than being the thing the site is built around.

The MkDocs relationship is more specific than a rivalry. Sourcey reads `mkdocs.yml` and imports `docs_dir` and `nav`, so an existing MkDocs site is a migration source. If your markdown is already structured for MkDocs, the import path exists. What does not exist, per the README, is a story for MkDocs plugins and theme customization.

The Doxygen comparison is the sharpest one, because Sourcey is not replacing Doxygen, it is replacing the pipeline after it. You still run Doxygen to produce XML. What disappears is the Breathe, Exhale and Sphinx chain and its Python environment. The README frames the win as "no new parser, no four-tool Breathe/Exhale/Sphinx pipeline". If your team is happy in Sphinx and already has the pipeline working, the migration buys you a different theme and a different config file, and it costs you a re-render of every page.

Licence, maintenance and what a version bump costs you

Sourcey is AGPL-3.0. That matters more for a documentation tool than it might first appear, because the natural way to use it is to run it in CI and publish the output. The AGPL's network clause is about offering a modified version of the program to users over a network, not about the HTML you generate, but the boundary between the two is a legal question and not one to settle from a README. If you intend to fork the CLI, embed it in a hosted service, or ship a modified binary, get that reviewed rather than assuming the output-versus-program split covers you.

On maintenance: the repository is not archived, and the last push was on 2026-09-10. Recent releases are v3.6.5 on 2026-07-12, v3.6.4 on 2026-06-23 and v3.6.3 on 2026-06-17, so the release cadence in that window was roughly monthly. The `package.json` version is 3.6.5, matching the latest release tag.

The upgrade cost is not uniform across adapters. If you use OpenAPI, markdown and MCP, an upgrade is an npm version bump and a rebuild. If you use the Rust path, the npm package carries `rust/sourcey-rustdoc` with its own `Cargo.toml` and `Cargo.lock`, so the Rust converter has its own dependency graph that moves on its own schedule. The Go path is similar: `go/sourcey-godoc` is a separate module with its own `go.mod` and is also installable standalone via `go install`, Homebrew or Scoop. That means the Go and Rust sides can be adopted without the JavaScript toolchain at all, and they can also drift from the Node package's release timing. Pin the version you build with rather than tracking `latest`, which is what the Dockerfile's `ARG SOURCEY_VERSION=latest` default does.

Editorial conclusion

Adopt Sourcey if your API reference already lives in OpenAPI, Doxygen XML, godoc or rustdoc and you want the rendered site committed and deployed like any other static asset. Skip it if you need a hosted editor, per-page permissions or non-technical authors editing in a browser, since every source here is a file in a repository. Before committing, verify three things: that your spec or XML output is accepted by the adapter you need, that `sourcey build` produces the pages you expect in dist/, and that AGPL-3.0 fits how you intend to distribute the tool and any modifications to it.

Frequently asked questions

Official sources

1. License: AGPL-3.0
2. Project website
3. README
4. Releases
5. sourcey/sourcey on GitHub