sourcey 3.5.9 → 3.5.10

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,18 @@ 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
+- **Rich guides**: markdown pages with steps, cards, accordions, syntax-highlighted code blocks, and prose alongside your API reference
+- **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. 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,22 +39,6 @@ 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

package/dist/client/sidebar.js

@@ -4,7 +4,176 @@
 // backdrop click, nav link click, Escape (native dialog behavior).
 // Dropdown toggles list visibility for tab selection.
 (function () {
+  function storageGet(key) {
+    try {
+      return window.sessionStorage.getItem(key);
+    } catch {
+      return null;
+    }
+  }
+
+  function storageSet(key, value) {
+    try {
+      window.sessionStorage.setItem(key, value);
+    } catch {
+      // Ignore blocked storage. Sidebar navigation still works normally.
+    }
+  }
+
+  function storageRemove(key) {
+    try {
+      window.sessionStorage.removeItem(key);
+    } catch {
+      // Ignore blocked storage. Sidebar navigation still works normally.
+    }
+  }
+
+  function normalizePath(pathname) {
+    var clean = (pathname || '/').replace(/\/+$/, '') || '/';
+    clean = clean.replace(/\/index(?:\.html)?$/, '') || '/';
+    clean = clean.replace(/\.html$/, '');
+    return clean || '/';
+  }
+
+  function commonPath(paths) {
+    if (!paths.length) return null;
+    var parts = paths.map(function (path) {
+      return normalizePath(path).split('/').filter(Boolean);
+    });
+    var common = [];
+
+    for (var i = 0; i < parts[0].length; i++) {
+      var part = parts[0][i];
+      var allMatch = parts.every(function (segments) {
+        return segments[i] === part;
+      });
+      if (!allMatch) break;
+      common.push(part);
+    }
+
+    return '/' + common.join('/');
+  }
+
+  function navScope(nav) {
+    var paths = [];
+    nav.querySelectorAll('a.nav-link[href]').forEach(function (link) {
+      var href = link.getAttribute('href');
+      if (!href || href.startsWith('#')) return;
+
+      try {
+        var url = new URL(href, window.location.href);
+        if (url.origin === window.location.origin) {
+          paths.push(url.pathname);
+        }
+      } catch {
+        // Ignore malformed hrefs.
+      }
+    });
+
+    return commonPath(paths);
+  }
+
+  function searchIndexScope() {
+    var meta = document.querySelector('meta[name="sourcey-search"]');
+    var content = meta && meta.getAttribute('content');
+    if (!content) return null;
+
+    try {
+      var url = new URL(content, window.location.href);
+      if (url.origin === window.location.origin) {
+        return normalizePath(url.pathname.replace(/\/search-index\.json$/, ''));
+      }
+    } catch {
+      // Ignore malformed metadata.
+    }
+
+    return null;
+  }
+
+  function sidebarStorageKey(scroller, nav) {
+    var tab = scroller.getAttribute('data-sourcey-sidebar-tab') || 'default';
+    var scope = navScope(nav) || searchIndexScope() || normalizePath(window.location.pathname);
+    return 'sourcey:sidebar-scroll:v1:' + window.location.origin + scope + ':' + tab;
+  }
+
+  function clampSidebarScroll(scroller, top) {
+    var max = Math.max(0, scroller.scrollHeight - scroller.clientHeight);
+    return Math.max(0, Math.min(top, max));
+  }
+
+  function saveSidebarScroll(scroller, key) {
+    storageSet(key, String(Math.round(scroller.scrollTop || 0)));
+  }
+
+  function restoreSidebarScroll(scroller, key) {
+    var raw = storageGet(key);
+    if (raw === null) return false;
+    storageRemove(key);
+
+    var top = Number(raw);
+    if (!Number.isFinite(top) || top <= 0) return false;
+
+    function apply() {
+      scroller.scrollTop = clampSidebarScroll(scroller, top);
+    }
+
+    apply();
+    requestAnimationFrame(apply);
+    return true;
+  }
+
+  function revealActiveSidebarLink(nav) {
+    var active = nav.querySelector('.nav-link.active');
+    if (!active) return;
+    requestAnimationFrame(function () {
+      active.scrollIntoView({ block: 'nearest', behavior: 'auto' });
+    });
+  }
+
+  function shouldSaveForNavigation(e, link) {
+    if (!link || e.defaultPrevented) return false;
+    if (e.button !== undefined && e.button !== 0) return false;
+    if (e.metaKey || e.ctrlKey || e.shiftKey || e.altKey) return false;
+    if (link.hasAttribute('download')) return false;
+
+    var target = link.getAttribute('target');
+    if (target && target.toLowerCase() !== '_self') return false;
+
+    var href = link.getAttribute('href');
+    if (!href || href.startsWith('#')) return false;
+
+    try {
+      var url = new URL(href, window.location.href);
+      if (url.origin !== window.location.origin) return false;
+      if (url.pathname === window.location.pathname && url.search === window.location.search && url.hash) {
+        return false;
+      }
+      return url.protocol === 'http:' || url.protocol === 'https:';
+    } catch {
+      return false;
+    }
+  }
+
+  function initDesktopSidebarScroll() {
+    var scroller = document.querySelector('[data-sourcey-sidebar-scroll]');
+    var nav = document.getElementById('nav');
+    if (!scroller || !nav) return;
+
+    var key = sidebarStorageKey(scroller, nav);
+    var restored = restoreSidebarScroll(scroller, key);
+    if (!restored) revealActiveSidebarLink(nav);
+
+    nav.addEventListener('click', function (e) {
+      var link = e.target.closest('a[href]');
+      if (shouldSaveForNavigation(e, link)) {
+        saveSidebarScroll(scroller, key);
+      }
+    });
+  }
+
   function init() {
+    initDesktopSidebarScroll();
+
     var dialog = document.getElementById('mobile-nav');
     var openBtns = document.querySelectorAll('[data-drawer-slide]');
     if (!dialog) return;

package/dist/components/layout/Sidebar.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Sidebar.d.ts","sourceRoot":"","sources":["../../../src/components/layout/Sidebar.tsx"],"names":[],"mappings":"AA+FA;;GAEG;AACH,wBAAgB,OAAO,wCAuGtB"}
+{"version":3,"file":"Sidebar.d.ts","sourceRoot":"","sources":["../../../src/components/layout/Sidebar.tsx"],"names":[],"mappings":"AA+FA;;GAEG;AACH,wBAAgB,OAAO,wCA2GtB"}

package/dist/components/layout/Sidebar.js

@@ -58,7 +58,7 @@ export function Sidebar() {
     const primaryAction = site.navbar.primary;
     const groups = activeTab.groups;
     const logoHref = site.logo?.href ?? `${base}${nav.tabs[0]?.href ?? ""}`;
-    return (_jsxs(_Fragment, { children: [_jsx("div", { id: "sidebar", class: "z-20 hidden lg:block fixed bottom-0 right-auto w-[18rem]", style: "top: var(--header-height)", children: _jsx("div", { class: "absolute inset-0 z-10 overflow-auto pr-8 pb-10", children: _jsxs("div", { class: "relative text-sm leading-6", children: [_jsx("div", { class: "sticky top-0 h-8 z-10 bg-gradient-to-b from-[rgb(var(--color-background-light))] dark:from-[rgb(var(--color-background-dark))]" }), _jsx("nav", { id: "nav", role: "navigation", children: _jsx(NavGroups, { groups: groups, activePageSlug: nav.activePageSlug, base: base }) })] }) }) }), _jsxs("dialog", { id: "mobile-nav", class: "mobile-nav-dialog", children: [site.logo?.light && (_jsx("div", { class: "px-4 py-4 border-b border-[rgb(var(--color-gray-200)/0.7)] dark:border-[rgb(var(--color-gray-800)/0.5)] shrink-0", children: _jsx(Logo, { href: logoHref, logo: site.logo, height: "h-6" }) })), nav.tabs.length > 1 && (_jsx("div", { class: "pt-5 px-4 shrink-0", children: _jsxs("div", { class: "drawer-dropdown", children: [_jsxs("button", { id: "drawer-group-toggle", type: "button", class: "drawer-dropdown-trigger", "aria-expanded": "false", children: [_jsx("span", { class: "drawer-dropdown-label", children: activeTab.label }), _jsx(DropdownChevron, {})] }), _jsx("ul", { id: "drawer-group-list", class: "drawer-dropdown-list", style: "display:none", children: nav.tabs.map((tab) => (_jsx("li", { children: _jsx("a", { href: `${base}${tab.href}`, class: `drawer-dropdown-item${tab.slug === nav.activeTabSlug ? " active" : ""}`, children: tab.label }) }, tab.slug))) })] }) })), _jsx("nav", { class: "pt-5 pb-3 px-4 flex-1 overflow-y-auto", children: _jsx(NavGroups, { groups: groups, activePageSlug: nav.activePageSlug, base: base }) }), (links.length > 0 || primaryAction) && (_jsx("div", { class: "px-4 py-3 border-t border-[rgb(var(--color-gray-200)/0.7)] dark:border-[rgb(var(--color-gray-800)/0.5)] shrink-0", children: _jsxs("ul", { class: "space-y-3", children: [links.map((link) => {
+    return (_jsxs(_Fragment, { children: [_jsx("div", { id: "sidebar", class: "z-20 hidden lg:block fixed bottom-0 right-auto w-[18rem]", style: "top: var(--header-height)", children: _jsx("div", { class: "absolute inset-0 z-10 overflow-auto pr-8 pb-10", "data-sourcey-sidebar-scroll": true, "data-sourcey-sidebar-tab": nav.activeTabSlug || "default", children: _jsxs("div", { class: "relative text-sm leading-6", children: [_jsx("div", { class: "sticky top-0 h-8 z-10 bg-gradient-to-b from-[rgb(var(--color-background-light))] dark:from-[rgb(var(--color-background-dark))]" }), _jsx("nav", { id: "nav", role: "navigation", children: _jsx(NavGroups, { groups: groups, activePageSlug: nav.activePageSlug, base: base }) })] }) }) }), _jsxs("dialog", { id: "mobile-nav", class: "mobile-nav-dialog", children: [site.logo?.light && (_jsx("div", { class: "px-4 py-4 border-b border-[rgb(var(--color-gray-200)/0.7)] dark:border-[rgb(var(--color-gray-800)/0.5)] shrink-0", children: _jsx(Logo, { href: logoHref, logo: site.logo, height: "h-6" }) })), nav.tabs.length > 1 && (_jsx("div", { class: "pt-5 px-4 shrink-0", children: _jsxs("div", { class: "drawer-dropdown", children: [_jsxs("button", { id: "drawer-group-toggle", type: "button", class: "drawer-dropdown-trigger", "aria-expanded": "false", children: [_jsx("span", { class: "drawer-dropdown-label", children: activeTab.label }), _jsx(DropdownChevron, {})] }), _jsx("ul", { id: "drawer-group-list", class: "drawer-dropdown-list", style: "display:none", children: nav.tabs.map((tab) => (_jsx("li", { children: _jsx("a", { href: `${base}${tab.href}`, class: `drawer-dropdown-item${tab.slug === nav.activeTabSlug ? " active" : ""}`, children: tab.label }) }, tab.slug))) })] }) })), _jsx("nav", { class: "pt-5 pb-3 px-4 flex-1 overflow-y-auto", children: _jsx(NavGroups, { groups: groups, activePageSlug: nav.activePageSlug, base: base }) }), (links.length > 0 || primaryAction) && (_jsx("div", { class: "px-4 py-3 border-t border-[rgb(var(--color-gray-200)/0.7)] dark:border-[rgb(var(--color-gray-800)/0.5)] shrink-0", children: _jsxs("ul", { class: "space-y-3", children: [links.map((link) => {
                                     const label = link.label ?? socialLabels[link.type] ?? link.href;
                                     return (_jsx("li", { children: _jsxs("a", { href: link.href, target: "_blank", rel: "noopener noreferrer", class: "flex items-center gap-2.5 text-[rgb(var(--color-gray-600))] hover:text-[rgb(var(--color-gray-900))] dark:text-[rgb(var(--color-gray-400))] dark:hover:text-[rgb(var(--color-gray-200))]", children: [link.type !== "link" && _jsx(SocialIcon, { type: link.type }), _jsx("span", { children: label })] }) }, link.href));
                                 }), primaryAction && (_jsx("li", { children: _jsxs("a", { href: primaryAction.href, target: "_blank", class: "group relative flex items-center justify-center px-4 py-2 text-sm font-medium", children: [_jsx("span", { class: "absolute inset-0 bg-[rgb(var(--color-primary-dark))] rounded-lg group-hover:opacity-90" }), _jsx("span", { class: "z-10 text-white", children: primaryAction.label })] }) }))] }) }))] })] }));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sourcey",
-  "version": "3.5.9",
+  "version": "3.5.10",
   "description": "Precision documentation from OpenAPI, MCP, Doxygen, godoc, and Markdown. Static HTML you own.",
   "type": "module",
   "engines": {
@@ -45,7 +45,7 @@
     "jiti": "^2.6.1",
     "js-yaml": "^4.1.0",
     "marked": "^15.0.0",
-    "mcp-parser": "^0.2.0",
+    "mcp-parser": "^0.4.0",
     "moxygen": "^2.1.1",
     "preact": "^10.28.4",
     "preact-render-to-string": "^6.6.6",