sourcey 3.5.9 → 3.6.0

package/README.md

@@ -1,8 +1,10 @@
 # Sourcey
 
-> Your API docs shouldn't depend on someone else's SaaS.
+> Docs straight from the source.
 
-Sourcey is an open source documentation platform. Point it at an OpenAPI spec, an MCP server, a Doxygen XML directory, or a Go module; add markdown guides; get a complete docs site. Static HTML you own; no dashboard, no monthly bill, no API calls to render your own documentation. Deploy anywhere.
+Sourcey tells the whole product story. It turns specs, code, rich guides, changelog, roadmap pages, examples, and portable context files from your project into static HTML you can deploy anywhere.
+
+No dashboard. No runtime. No API calls to render your own documentation.
 
 [![npm](https://img.shields.io/npm/v/sourcey)](https://www.npmjs.com/package/sourcey)
 [![build](https://img.shields.io/github/actions/workflow/status/sourcey/sourcey/ci.yml?branch=main)](https://github.com/sourcey/sourcey/actions)
@@ -17,17 +19,19 @@ npx sourcey init
 
 ![Sourcey](assets/hero-preview.jpg)
 
-**[Live demo](https://cheesestore.github.io/)** · [Documentation](https://sourcey.com/docs) · [GitHub](https://github.com/sourcey/sourcey)
+**[Live demo](https://sourcey.com/cheesestore)** · [Documentation](https://sourcey.com/docs) · [GitHub](https://github.com/sourcey/sourcey)
 
 ## 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, auto-generated code samples in 10 languages (cURL, JavaScript, TypeScript, Python, Go, Ruby, Java, PHP, Rust, C#)
 - **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
-- **Markdown guides with rich components**: steps, cards, accordions, syntax-highlighted code blocks; prose docs alongside your API reference
-- **C++ and Doxygen**: feed Doxygen XML output, get modern searchable API docs. No new parser, no four-tool Breathe/Exhale/Sphinx pipeline
+- **Rich guides**: markdown pages with steps, cards, accordions, syntax-highlighted code blocks, and prose alongside your API reference
+- **MkDocs source import**: point a tab at `mkdocs.yml`; Sourcey reads `docs_dir` and `nav` so existing MkDocs markdown sites can render without hand-copying the sidebar structure
+- **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
-- **llms.txt generation**: auto-generate llms.txt and llms-full.txt alongside your HTML. Docs serve developers and AI agents from one build
+- **Context exports**: auto-generate llms.txt and llms-full.txt alongside your HTML as alternate views of the same documentation graph
 - **TypeScript config**: `sourcey.config.ts` with `defineConfig()` autocomplete; theme, navbar, CTA buttons, footer
 - **Theme presets**: default (sidebar + TOC), minimal (single column), api-first (Stripe-style three column); 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
@@ -36,34 +40,18 @@ npx sourcey init
 - **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
 
-### Sourcey vs alternatives
-
-| | Sourcey | Redocly | GitBook | Mintlify | Fern | ReadMe |
-|---|---|---|---|---|---|---|
-| Open source | Yes | Partial | No | No | No | No |
-| Static output | Yes | Yes | No | No | No | No |
-| Zero JS shipped | Yes | No | No | No | No | No |
-| MCP server docs | Native | No | No | No | No | No |
-| Doxygen / C++ docs | Native | No | No | No | No | No |
-| godoc / Go docs | Native | No | No | No | No | No |
-| Config format | TypeScript | YAML | GUI | JSON | YAML | GUI |
-| Local preview | Vite SSR | Local | Hosted | Local | Local | Hosted |
-| No account required | Yes | Partial | No | No | No | No |
-| Self-hosted | Yes | Yes | No | No | Yes | No |
-| Pricing | Free | $10–$24 | $65–$249 | $250+ | $150+ | $79–$3,000+ |
-
 ## Install
 
 ### Sourcey CLI
 
 The full Sourcey binary handles OpenAPI, Doxygen, godoc, MCP, and Markdown sources.
 
-| Path     | Command                                            | Requires          |
-|----------|----------------------------------------------------|-------------------|
-| npm      | `npm install -g sourcey`                           | Node 20+          |
-| 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)      |
+| Path     | Command                                        | Requires          |
+| -------- | ---------------------------------------------- | ----------------- |
+| npm      | `npm install -g sourcey`                       | Node 20+          |
+| 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.
 
@@ -71,10 +59,10 @@ Then `sourcey init` to scaffold a new project, or `sourcey build` against an exi
 
 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` |
+| 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` |
 
 ## Quick start
@@ -95,101 +83,29 @@ sourcey dev
 Create `sourcey.config.ts` in your project root:
 
 ```typescript
-import { defineConfig } from "sourcey";
+import { defineConfig, openapi } from "sourcey";
 
 export default defineConfig({
   name: "My API",
-  theme: {
-    preset: "default",  // "default" | "minimal" | "api-first"
-    colors: {
-      primary: "#6366F1",
-      light: "#818CF8",
-      dark: "#4F46E5",
-    },
-  },
-  logo: "./logo.png",
   navigation: {
-    tabs: [
-      {
-        tab: "Documentation",
-        groups: [
-          {
-            group: "Getting Started",
-            pages: ["introduction", "quickstart", "authentication"],
-          },
-        ],
-      },
-      {
-        tab: "API Reference",
-        openapi: "./openapi.yaml",
-      },
-      {
-        tab: "MCP Server",
-        mcp: "./mcp.json",
-      },
-    ],
-  },
-  navbar: {
-    links: [{ type: "github", href: "https://github.com/you/repo" }],
-    primary: { type: "button", label: "Dashboard", href: "https://app.example.com" },
-  },
-  footer: {
-    socials: { github: "https://github.com/you/repo" },
+    tabs: [{ tab: "API Reference", source: openapi("./openapi.yaml") }],
   },
 });
 ```
 
-Each tab is an `openapi` spec, an `mcp` snapshot, a `doxygen` directory, a `godoc` Go module, or `groups` of markdown pages. Pages are referenced by slug (e.g. `"quickstart"` resolves to `quickstart.md`).
+Each tab has one `source`, usually created with `markdown()`, `mkdocs()`, `openapi()`, `mcp()`, `doxygen()`, or `godoc()`. Pages are referenced by slug (e.g. `"quickstart"` resolves to `quickstart.md`). See [docs/configuration.md](docs/configuration.md) for theme, navbar, footer, logo, and full tab options.
 
 ### Go documentation (godoc)
 
-Add a Go module as a tab and Sourcey extracts package docs natively (no Doxygen pipeline):
-
-```typescript
-{
-  tab: "Go API",
-  godoc: {
-    module: ".",
-    packages: ["./internal/core/...", "./cmd/..."],
-    // sourceBasePath: "go/my-module" // repo-relative prefix for source links when module is not at repo root
-    // mode: "auto"   // default; live when Go is available, snapshot otherwise
-    // includeTests: true       // examples from *_test.go (default)
-    // includeUnexported: false // hide unexported symbols (default)
-  },
-}
-```
-
-The string shorthand is `godoc: "."` and expands to `{ module: ".", packages: ["./..."], mode: "auto", includeTests: true }`.
+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.
 
-`editBasePath` remains the global base for Markdown "Edit this page" links.
-Use `godoc.sourceBasePath` only when Go source files live under a different
-repository prefix than the docs source.
-
-Live mode invokes `go list` + `go/parser` + `go/doc` against the host Go toolchain. To pin a build environment for reproducibility, set `goEnv: { GOOS, GOARCH, tags }`.
-
-Snapshot mode reads a committed `godoc.json` and needs no Go on the build host. Generate it with:
-
-```bash
-sourcey godoc --module . --packages './...' --out docs/godoc.json
-```
-
-then point the tab at it:
+**[Live: scafld's Go API reference →](https://0state.com/scafld/docs/go-api)**
 
 ```typescript
-{
-  tab: "Go API",
-  godoc: { mode: "snapshot", snapshot: "./docs/godoc.json" },
-}
+{ tab: "Go API", source: godoc(".") }
 ```
 
-The extractor is also a standalone Go CLI for projects that want a native Go
-docs generator without installing the full Sourcey npm package:
-
-```bash
-go install github.com/sourcey/sourcey/go/sourcey-godoc/cmd/sourcey-godoc@latest
-sourcey-godoc generate --module . --packages './...' --out site
-sourcey-godoc snapshot --module . --packages './...' --out docs/godoc.json
-```
+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](docs/configuration.md) for `packages`, `mode`, `goEnv`, `sourceBasePath`, and `includeUnexported`.
 
 ### Markdown components
 
@@ -239,12 +155,7 @@ 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
 ```
 
-| Command | Flag | Description |
-| --- | --- | --- |
-| `build` | `--output, -o` | Output directory (default: `dist`) |
-| `build` | `--embed, -e` | Embeddable output (no html/body wrapper) |
-| `build` | `--quiet, -q` | Suppress output |
-| `dev` | `--port, -p` | Dev server port (default: `4400`) |
+Run `sourcey <command> --help` for flags.
 
 ## Development
 

package/dist/adapters/index.d.ts

@@ -0,0 +1,11 @@
+import type { DoxygenSourceOptions, GodocSourceOptions, MarkdownSourceOptions, McpSourceOptions, MkDocsSourceOptions, OpenApiSourceOptions, SourceAdapter } from "./types.js";
+import { assertLocalPath } from "./shared.js";
+export declare function openapi(specOrOptions: string | OpenApiSourceOptions): SourceAdapter;
+export declare function mcp(specOrOptions: string | McpSourceOptions): SourceAdapter;
+export declare function markdown(options: MarkdownSourceOptions): SourceAdapter;
+export declare function mkdocs(configOrOptions: string | MkDocsSourceOptions): SourceAdapter;
+export declare function doxygen(options: DoxygenSourceOptions): SourceAdapter;
+export declare function godoc(configOrPath: GodocSourceOptions): SourceAdapter;
+export { assertLocalPath };
+export type { DoxygenSourceOptions, GodocSourceOptions, MarkdownSourceOptions, McpSourceOptions, MkDocsSourceOptions, OpenApiSourceOptions, PageMarkdownOptions, ResolvedTabSource, SourceAdapter, SourceAdapterContext, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/adapters/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/adapters/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,oBAAoB,EACpB,kBAAkB,EAClB,qBAAqB,EACrB,gBAAgB,EAChB,mBAAmB,EACnB,oBAAoB,EACpB,aAAa,EACd,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,eAAe,EAAuC,MAAM,aAAa,CAAC;AAGnF,wBAAgB,OAAO,CAAC,aAAa,EAAE,MAAM,GAAG,oBAAoB,GAAG,aAAa,CAanF;AAED,wBAAgB,GAAG,CAAC,aAAa,EAAE,MAAM,GAAG,gBAAgB,GAAG,aAAa,CAa3E;AAED,wBAAgB,QAAQ,CAAC,OAAO,EAAE,qBAAqB,GAAG,aAAa,CAWtE;AAED,wBAAgB,MAAM,CAAC,eAAe,EAAE,MAAM,GAAG,mBAAmB,GAAG,aAAa,CAInF;AAED,wBAAgB,OAAO,CAAC,OAAO,EAAE,oBAAoB,GAAG,aAAa,CAsBpE;AAED,wBAAgB,KAAK,CAAC,YAAY,EAAE,kBAAkB,GAAG,aAAa,CA6BrE;AAMD,OAAO,EAAE,eAAe,EAAE,CAAC;AAC3B,YAAY,EACV,oBAAoB,EACpB,kBAAkB,EAClB,qBAAqB,EACrB,gBAAgB,EAChB,mBAAmB,EACnB,oBAAoB,EACpB,mBAAmB,EACnB,iBAAiB,EACjB,aAAa,EACb,oBAAoB,GACrB,MAAM,YAAY,CAAC"}

package/dist/adapters/index.js

@@ -0,0 +1,98 @@
+import { resolve } from "node:path";
+import { assertLocalPath, resolveMarkdownGroups, toWatchPaths } from "./shared.js";
+import { mkdocs as mkdocsAdapter } from "./mkdocs.js";
+export function openapi(specOrOptions) {
+    const spec = typeof specOrOptions === "string" ? specOrOptions : specOrOptions.spec;
+    return {
+        name: "openapi",
+        async resolve(ctx) {
+            if (ctx.isUrl(spec)) {
+                return { kind: "openapi", spec };
+            }
+            const absPath = ctx.resolvePath(spec);
+            await ctx.assertExists(absPath, `OpenAPI spec "${spec}" in tab "${ctx.tabName}"`);
+            return { kind: "openapi", spec: absPath, watchPaths: [absPath] };
+        },
+    };
+}
+export function mcp(specOrOptions) {
+    const spec = typeof specOrOptions === "string" ? specOrOptions : specOrOptions.spec;
+    return {
+        name: "mcp",
+        async resolve(ctx) {
+            if (ctx.isUrl(spec)) {
+                return { kind: "mcp", spec };
+            }
+            const absPath = ctx.resolvePath(spec);
+            await ctx.assertExists(absPath, `MCP spec "${spec}" in tab "${ctx.tabName}"`);
+            return { kind: "mcp", spec: absPath, watchPaths: [absPath] };
+        },
+    };
+}
+export function markdown(options) {
+    return {
+        name: "markdown",
+        async resolve(ctx) {
+            return {
+                kind: "markdown",
+                adapter: "markdown",
+                groups: await resolveMarkdownGroups(options.groups, ctx.tabName, ctx.configDir),
+            };
+        },
+    };
+}
+export function mkdocs(configOrOptions) {
+    const options = typeof configOrOptions === "string" ? { config: configOrOptions } : configOrOptions;
+    return mkdocsAdapter(options);
+}
+export function doxygen(options) {
+    return {
+        name: "doxygen",
+        async resolve(ctx) {
+            const absXml = ctx.resolvePath(options.xml);
+            await ctx.assertExists(absXml, `Doxygen XML directory "${options.xml}" in tab "${ctx.tabName}"`);
+            return {
+                kind: "doxygen",
+                config: {
+                    xml: absXml,
+                    language: options.language ?? "cpp",
+                    groups: options.groups ?? false,
+                    index: options.index === false ? "none" : (options.index ?? "auto"),
+                    sourceUrl: options.sourceUrl,
+                },
+                watchPaths: [absXml],
+            };
+        },
+    };
+}
+export function godoc(configOrPath) {
+    return {
+        name: "godoc",
+        async resolve(ctx) {
+            const cfg = typeof configOrPath === "string" ? { module: configOrPath } : configOrPath;
+            const moduleAbs = resolve(ctx.configDir, cfg.module ?? ".");
+            await ctx.assertExists(moduleAbs, `Go module directory "${cfg.module ?? "."}" in tab "${ctx.tabName}"`);
+            const snapshotAbs = cfg.snapshot ? ctx.resolvePath(cfg.snapshot) : undefined;
+            return {
+                kind: "godoc",
+                config: {
+                    module: moduleAbs,
+                    packages: cfg.packages?.length ? cfg.packages : ["./..."],
+                    snapshot: snapshotAbs,
+                    mode: cfg.mode ?? "auto",
+                    includeTests: cfg.includeTests ?? true,
+                    includeUnexported: cfg.includeUnexported ?? false,
+                    hideUndocumented: cfg.hideUndocumented ?? false,
+                    exclude: cfg.exclude ?? [],
+                    goEnv: cfg.goEnv,
+                    sourceBasePath: trimSlashes(cfg.sourceBasePath ?? ""),
+                },
+                watchPaths: toWatchPaths([snapshotAbs]),
+            };
+        },
+    };
+}
+function trimSlashes(value) {
+    return value.replace(/^\/+|\/+$/g, "");
+}
+export { assertLocalPath };

package/dist/adapters/mkdocs.d.ts

@@ -0,0 +1,5 @@
+import type { MarkdownPreprocessor } from "../core/markdown-loader.js";
+import type { MkDocsSourceOptions, SourceAdapter } from "./types.js";
+export declare function mkdocs(options: MkDocsSourceOptions): SourceAdapter;
+export declare const preprocessMkDocsMarkdown: MarkdownPreprocessor;
+//# sourceMappingURL=mkdocs.d.ts.map

package/dist/adapters/mkdocs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mkdocs.d.ts","sourceRoot":"","sources":["../../src/adapters/mkdocs.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AACvE,OAAO,KAAK,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAcrE,wBAAgB,MAAM,CAAC,OAAO,EAAE,mBAAmB,GAAG,aAAa,CAoBlE;AAiLD,eAAO,MAAM,wBAAwB,EAAE,oBAWtC,CAAC"}