Skip to content
Back to search

sourcey

Precision documentation from OpenAPI, MCP, Doxygen, and Markdown guides. Static HTML you own.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026. Its scripts were only partly scanned.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/sourcey/sourcey with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/sourcey/sourcey'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/sourcey--sourcey/badge.svg)](/listings/sourcey--sourcey)

HTML

<a href="/listings/sourcey--sourcey"><img src="/api/listings/sourcey--sourcey/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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.19+ | | 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](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.

| Path | Command | | -------- | ------------------------------------------------------------------------------------------------- | | Go | `go install github.com/sourcey/sourcey/go/sourcey-godoc/cmd/sourcey-godoc@latest` | | Homebrew | `brew install sourcey/tap/sourcey-godoc` | | Scoop | `scoop bucket add sourcey https://github.com/sourcey/scoop-bucket && scoop install sourcey-godoc` |

Rust snapshot converter

The `rustdoc()` adapter consumes nightly rustdoc JSON through the [`sourcey`](https://crates.io/crates/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](docs/adapters/rustdoc.md).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 15 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "sourcey",
  3. "description": "Sourcey's plugins for agents: building, migrating and reviewing documentation sites.",
  4. "owner": {
  5. "name": "Sourcey",
  6. "email": "hello@sourcey.com"
  7. },
  8. "plugins": [
  9. {
  10. "name": "sourcey-docs",
  11. "source": "./",
  12. "description": "Build, migrate and review documentation sites with Sourcey: Markdown guides, OpenAPI and MCP references, Doxygen, Go and Rust, from a project's own sources."
  13. }
  14. ]
  15. }
README.md · README · 245 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Sourcey
  2. > Docs straight from the source.
  3. 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.
  4. Everything renders at build time: no dashboard, no runtime, no API calls to render your own documentation.
  5. [![npm](https://img.shields.io/npm/v/sourcey)](https://www.npmjs.com/package/sourcey)
  6. [![build](https://img.shields.io/github/actions/workflow/status/sourcey/sourcey/ci.yml?branch=main)](https://github.com/sourcey/sourcey/actions)
  7. [![node](https://img.shields.io/node/v/sourcey)](https://nodejs.org)
  8. [![license](https://img.shields.io/npm/l/sourcey)](LICENSE)
  9. ```bash
  10. npx sourcey init
  11. ```
  12. ![Sourcey](assets/hero-preview.jpg)
  13. **[Live demo](https://sourcey.com/cheesestore)** · [Documentation](https://sourcey.com/docs) · [GitHub](https://github.com/sourcey/sourcey)
  14. ## Features
  15. - **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
  16. - **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
  17. - **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
  18. - **Rich guides**: markdown pages with steps, cards, accordions, syntax-highlighted code blocks, and prose alongside your API reference
  19. - **One-time migration**: convert an existing Astro, MkDocs, Docusaurus or Mintlify documentation project to native Sourcey Markdown and configuration, with a dry-run diff and checks for routes, fragments, content and media. [Migration guide](docs/migrating.md)
  20. - **Product story pages**: changelog, roadmap pages, examples, reference material, search, and portable context exports in one source-owned site
  21. - **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
  22. - **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
  23. - **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
  24. - **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
  25. - **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/machine-readable.md)
  26. - **Docs over MCP**: the optional [`sourcey-docs-mcp`](packages/docs-mcp) package searches and reads a built documentation directory. Its SDK stays out of the generator and browser bundle
  27. - **TypeScript config**: `sourcey.config.ts` with `defineConfig()` autocomplete; theme, navbar, CTA buttons, footer
  28. - **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
  29. - **Vite dev server**: SSR hot reload on every component and CSS change; spec and markdown changes trigger instant refresh
  30. - **Light and dark**: semantic design tokens, light and dark logo variants, the reader's choice saved and applied before the page draws
  31. - **Search in the browser**: full-text and typo-tolerant across every page, operation and symbol, loaded in shards as it is needed; Cmd+K
  32. - **Static HTML output**: no framework runtime, no vendor lock-in. Deploy to GitHub Pages, Vercel, Netlify, S3, anywhere
  33. - **Open source**: AGPL-3.0. Self-host, fork, extend. Your docs, your infrastructure
  34. ## Install
  35. ### Sourcey CLI
  36. The full Sourcey binary handles OpenAPI, MCP, Doxygen, godoc, rustdoc, and Markdown sources. Existing Astro, MkDocs, Docusaurus and Mintlify projects have one-time converters.
  37. | Path | Command | Requires |
  38. | -------- | ---------------------------------------------- | ---------------------------- |
  39. | npm | `npm install -g sourcey` | Node 22.22.2+, 24.15+ or 26+ |
  40. | Homebrew | `brew tap sourcey/tap && brew install sourcey` | macOS / Linuxbrew |
  41. | Docker | `docker run -v "$PWD":/docs sourcey/sourcey` | Docker |
  42. | Nix | `nix run github:sourcey/sourcey` | Nix (flakes) |
  43. Then `sourcey init` to scaffold a new project, or `sourcey build` against an existing one. See [docs/install.md](docs/install.md) for full Docker invocations (`init` / `dev` / `build`), the `--host` flag for containerized dev, Linuxbrew notes, and Nix profile install.
  44. ### Standalone Go docs generator
  45. [![Go Reference](https://pkg.go.dev/badge/github.com/sourcey/sourcey/go/sourcey-godoc.svg)](https://pkg.go.dev/github.com/sourcey/sourcey/go/sourcey-godoc)
  46. [![Go Report Card](https://goreportcard.com/badge/github.com/sourcey/sourcey/go/sourcey-godoc)](https://goreportcard.com/report/github.com/sourcey/sourcey/go/sourcey-godoc)
  47. 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.
  48. | Path | Command |
  49. | -------- | ------------------------------------------------------------------------------------------------- |
  50. | Go | `go install github.com/sourcey/sourcey/go/sourcey-godoc/cmd/sourcey-godoc@latest` |
  51. | Homebrew | `brew install sourcey/tap/sourcey-godoc` |
  52. | Scoop | `scoop bucket add sourcey https://github.com/sourcey/scoop-bucket && scoop install sourcey-godoc` |
  53. ### Rust snapshot converter
  54. [![crates.io](https://img.shields.io/crates/v/sourcey.svg)](https://crates.io/crates/sourcey)
  55. [![docs.rs](https://docs.rs/sourcey/badge.svg)](https://docs.rs/sourcey)
  56. The `rustdoc()` adapter consumes nightly rustdoc JSON through the [`sourcey`](https://crates.io/crates/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](docs/adapters/rustdoc.md).
  57. ## Quick start
  58. ```bash
  59. # Scaffold a project (detects OpenAPI specs and Doxyfiles)
  60. npx sourcey init
  61. # Dev server with hot reload
  62. sourcey dev
  63. # Build static HTML to dist/
  64. sourcey build
  65. # Quick build from a single OpenAPI spec
  66. sourcey build api.yaml -o dist/
  67. ```
  68. In CI, install the project's dependencies and run `npx sourcey build`; see [deploying](docs/deploying.md) for GitHub Pages, Netlify, Vercel and Cloudflare Pages.
  69. ### Astro integration
  70. 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.
  71. ```typescript
  72. // astro.config.ts
  73. import { defineConfig } from "astro/config";
  74. import sourcey from "sourcey/astro";
  75. export default defineConfig({
  76. site: "https://sourcey.com",
  77. integrations: [
  78. sourcey({
  79. config: "./sourcey.config.ts",
  80. routeBase: "/docs",
  81. }),
  82. ],
  83. });
  84. ```
  85. You can also share an imported config object when you want one config module to feed both the CLI and Astro:
  86. ```typescript
  87. import { defineConfig } from "astro/config";
  88. import sourcey from "sourcey/astro";
  89. import docs from "./sourcey.config";
  90. export default defineConfig({
  91. site: "https://sourcey.com",
  92. integrations: [sourcey({ config: docs, configDir: ".", routeBase: "/docs" })],
  93. });
  94. ```
  95. 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.
  96. ## Configuration
  97. Create `sourcey.config.ts` in your project root:
  98. ```typescript
  99. import { defineConfig, openapi } from "sourcey";
  100. export default defineConfig({
  101. name: "My API",
  102. navigation: {
  103. tabs: [{ tab: "API Reference", source: openapi("./openapi.yaml") }],
  104. },
  105. });
  106. ```
  107. 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 [configuration](docs/configuration.md) for the site's settings, [navigation](docs/navigation.md) for tabs, groups and pages, and [themes](docs/themes.md) for colours, fonts and layout.
  108. ### Go documentation (godoc)
  109. 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.
  110. **[Live: scafld's Go API reference →](https://auscaster.com/scafld/docs/go-api)**
  111. ```typescript
  112. { tab: "Go API", source: godoc(".") }
  113. ```
  114. 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 the [Go guide](docs/guides/godoc-go.md) for `packages`, `mode`, `goEnv`, `sourceBasePath`, and `includeUnexported`.
  115. ### Markdown components
  116. Guides support rich components in standard markdown:
  117. ```markdown
  118. <Steps>
  119. <Step title="Install">Run `npm install sourcey`</Step>
  120. <Step title="Configure">Create `sourcey.config.ts`</Step>
  121. <Step title="Build">Run `sourcey build`</Step>
  122. </Steps>
  123. <CardGroup cols={2}>
  124. <Card title="API Reference" icon="book-open" href="/api">Full endpoint docs</Card>
  125. <Card title="Guides" icon="map" href="/docs">Step-by-step tutorials</Card>
  126. </CardGroup>
  127. <AccordionGroup>
  128. <Accordion title="How does auth work?">We use API keys and OAuth2.</Accordion>
  129. </AccordionGroup>
  130. ```
  131. ### Theme
  132. All visual configuration lives under `theme`. `theme.name` selects the complete renderer; colors, fonts, layout dimensions, and custom CSS apply on top:
  133. ```typescript
  134. theme: {
  135. name: "api-first",
  136. colors: { primary: "#f59e0b", light: "#fbbf24", dark: "#d97706" },
  137. fonts: { sans: "Lexend", mono: "Fira Code" },
  138. layout: { sidebar: "16rem", content: "48rem" },
  139. css: ["./brand.css"],
  140. }
  141. ```
  142. 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; a named font loads from Google Fonts. Theme-specific options are only interpreted by the selected theme. See [themes](docs/themes.md).
  143. ## CLI
  144. ```bash
  145. sourcey init Start a project (detects OpenAPI specs and Doxyfiles)
  146. sourcey dev Dev server (reads sourcey.config.ts)
  147. sourcey build Build site (reads sourcey.config.ts)
  148. sourcey build api.yaml Quick build from a single spec
  149. sourcey check Check sources, routes and links without writing
  150. sourcey validate api.yaml Validate a spec file
  151. sourcey migrate mkdocs Convert an Astro, MkDocs, Docusaurus or Mintlify project
  152. sourcey godoc --out godoc.json Snapshot a Go module's docs to JSON
  153. sourcey-godoc generate --out site Standalone Go CLI for static godoc sites
  154. ```
  155. Run `sourcey <command> --help` for flags, or see [the CLI reference](docs/cli/build.md).
  156. ## Agent skill
  157. The [Sourcey skill](skills/sourcey/SKILL.md) 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:
  158. ```bash
  159. # Claude Code
  160. /plugin marketplace add sourcey/sourcey
  161. /plugin install sourcey-docs@sourcey
  162. # Gemini CLI
  163. gemini extensions install https://github.com/sourcey/sourcey
  164. ```
  165. 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`](https://github.com/sourcey/mcp-server); this one is for the documentation generator.
  166. ## Development
  167. ```bash
  168. git clone https://github.com/sourcey/sourcey.git
  169. cd sourcey && npm install
  170. npm run build && npm test
  171. cd go/sourcey-godoc && go test ./... && go vet ./...
  172. # Run the in-repo docs site against your working copy
  173. cd docs && npx tsx ../src/cli.ts dev
  174. ```
  175. ## License
  176. [AGPL-3.0](LICENSE).
  177. Commercial licensing available; contact [sourcey.com](https://sourcey.com).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.