Most documentation-tool demos begin with a polished example and end before the awkward part: the tool has to meet an existing project where the API, prose, and deployment assumptions were not designed for it.
I tried Sourcey on a small but real boundary in TRAVIS, a local application I am building. The boundary has a loopback health endpoint and an owner-action endpoint. It is not a sample pet-store API. The service was running while I wrote the spec, and the fields in the spec came from the response shape I was actually observing.
My question was narrow: could I turn one OpenAPI file and one human-written guide into a static documentation site without adding a documentation server to the application?
The answer was yes. The interesting part was what appeared beside the HTML.
The project I used
I documented two TRAVIS routes:
-
GET /healthz, which reports the process identity and whether the canonical capability fabric is ready. -
POST /api/action, which accepts a named owner action and its structured input.
The OpenAPI document is intentionally modest: 54 lines, two paths, and only the response fields a reader needs in order to understand readiness. Alongside it I wrote a short Markdown introduction explaining why the action boundary needs an idempotency identity.
The Sourcey configuration joins those sources into two tabs: Guides and API Reference. This matters more than it sounds. The guide remains prose written for a person, while the reference comes from the machine-readable contract. I did not have to copy endpoint fields into a second Markdown table that would drift later.
The commands I ran
The project uses Node 24.19.0. Sourcey's current installation guide requires Node 20 or later, so the runtime met the documented floor. I added Sourcey as a local dependency, then ran:
npm install
npm run docs:build
The script behind the second command is simply sourcey build.
The install added 251 packages and npm reported zero known vulnerabilities at the time of the run. The build printed:
Sourcey: building documentation site
Pages: 2
Output: ...\sourcey-frantic-127-demo\dist
Time: 92.1s
The 92 seconds deserve context. This was a cold Windows run immediately after install, not a warm incremental build. I would measure repeat builds before putting it on a latency-sensitive CI path. I would not turn one cold number into a performance claim.
What landed in dist/
The output directory contained 11 files totaling 440,495 bytes:
api.html
index.html
introduction.html
llms-full.txt
llms.txt
search-index.json
sitemap.xml
sourcey.css
sourcey.js
_og/api.png
_og/introduction.png
That list explains Sourcey's value better than a feature grid.
api.html is the generated reference. introduction.html is the human guide. The search index joins both. The sitemap makes the pages discoverable to ordinary crawlers. The two llms files expose the same documentation to tools that prefer plain text. The Open Graph images were generated as part of the same build.
In other words, I supplied one contract and one guide; the build supplied several ways to read the result without making me maintain several versions of the facts.
The output is static. There is no documentation database and no documentation runtime to operate beside TRAVIS. That makes the deployment boundary easy to reason about: serve the directory from a normal static host, and rebuild it when the spec or guide changes.
What I liked
The best design choice is that Sourcey does not force prose and reference material into the same authoring format. OpenAPI remains OpenAPI. The explanation remains Markdown. The navigation configuration decides how readers encounter them.
The second useful choice is that search and agent-readable exports are outputs, not separate projects. A team can still review openapi.yaml and introduction.md as the sources of truth.
The generated files also make verification straightforward. For this run I recorded SHA-256 hashes for index.html, llms.txt, and llms-full.txt. That is not glamorous, but it gives a CI job a precise artifact identity instead of a vague "docs built" message.
What I would change before production
I would add a contract check that calls the live loopback service and compares its response shape with the OpenAPI schema. Sourcey can faithfully render a wrong spec; rendering and truth are different jobs.
I would also pin the Sourcey version instead of leaving the demonstration on latest, then run the build in CI and publish only the hashed dist/ artifact. Finally, I would add error responses and authentication semantics to the action route before calling the reference complete.
Those are application responsibilities, not reasons to avoid the tool. Sourcey did the part I asked it to do: it turned real project sources into a coherent, portable documentation bundle.
Reproduce the walkthrough
The public Sourcey overview shows the same basic lifecycle—initialize, develop, then build—and describes OpenAPI, Markdown, search, static output, and agent-readable context files. The installation and quick-start pages document the Node requirement and commands. Start with the Sourcey open-source overview, then use the installation guide and quick start.
For my test, the decisive evidence was not the marketing copy. It was the directory on disk: two readable pages, a search index, a sitemap, two context exports, and social images, all produced from one real API contract and one guide.
Top comments (1)
The live-schema check is the important complement. I would also version the generated docs alongside the API contract and surface a diff that distinguishes additive, breaking, and documentation-only changes. That gives reviewers a concrete reason to rebuild—and helps prevent a clean static artifact from masking an incompatible response change.