# Sourcey

> Sourcey tells the whole product story. Specs, code, rich guides, changelog, roadmap pages, examples, and portable context files from your project as static HTML.

## Documentation

- [Introduction](/docs/introduction): Sourcey tells the whole product story. Specs, code, rich guides, changelog, roadmap pages, examples, and portable context files from your project as static HTML.
- [Install](/docs/install): Every supported install path for Sourcey. npm, Homebrew, Docker, and Nix for the main CLI. Go, Homebrew, and Scoop for the standalone Go docs generator.
- [Quick Start](/docs/quickstart): From zero to a running docs site in under a minute.
- [Project Structure](/docs/project-structure): How sourcey finds your config, markdown files, and OpenAPI specs.
- [Writing Pages](/docs/writing-pages): Markdown files with frontmatter. Title, description, and content.
- [Components](/docs/components): Rich components in plain markdown. No JSX, no imports, just directives.
- [OpenAPI Integration](/docs/openapi-integration): Point sourcey at a spec. Get a complete API reference with code samples.
- [MCP Integration](/docs/mcp-integration): Document MCP servers with tools, resources, and prompts rendered as browsable reference docs.
- [Themes & Layout](/docs/themes-and-layout): Three presets, custom colors, fonts, layout dimensions, and CSS overrides.
- [Dark Mode](/docs/dark-mode): Built in. localStorage persistence. Light and dark logo variants.
- [Search](/docs/search): Client-side fuzzy search. Cmd+K. Works offline.
- [Deploying](/docs/deploying): Static HTML. Deploy to GitHub Pages, Vercel, Netlify, S3, or anywhere.
- [Changelog](/docs/changelog): All notable changes to Sourcey. Format based on [Keep a Changelog](https://keepachangelog.com/).

## Guides

- [Your First Docs Site](/docs/guides/guide-first-docs-site): Build a complete documentation site from scratch. API reference plus markdown guides.
- [Custom Branding](/docs/guides/guide-custom-branding): Your colors, your fonts, your logo. Make it yours.
- [Multi-Tab Sites](/docs/guides/guide-multi-tab-sites): Combine markdown guides, API reference, and more in a single site.
- [Tutorial: Document Your MCP Server](/docs/guides/guide-mcp-docs): Generate browsable documentation from an MCP server in five minutes.
- [Go / godoc Docs](/docs/guides/guide-godoc-go): Generate Go API reference from package comments, exported symbols, and examples.
- [Doxygen / C++ Docs](/docs/guides/guide-doxygen-cpp): Generate API reference from Doxygen XML output.
- [Embedding in Existing Sites](/docs/guides/guide-embedding): Add sourcey docs as a subfolder in your existing website.
- [Build Ask AI with Sourcey and LangChain](/docs/guides/guide-langchain-retriever): Implement your own Ask AI feature over a Sourcey docs site.
- [Generating mcp.json](/docs/guides/mcp-snapshot): Snapshot a running MCP server or write the spec by hand.
- [MCP Ecosystem](/docs/guides/mcp-ecosystem): mcp-schema and mcp-parser, TypeScript tooling for MCP server specifications.

## Configuration

- [sourcey.config.ts](/docs/config/ref-config): Full configuration reference. Every option, every type.
- [Theme Tokens](/docs/config/ref-theme-tokens): Colors, fonts, layout dimensions, and CSS overrides.
- [Navigation](/docs/config/ref-navigation): Tabs, groups, pages, and slugs.
- [Navbar & Footer](/docs/config/ref-navbar-footer): Links, social icons, and CTA buttons.
- [Code Samples](/docs/config/ref-code-samples): Auto-generated code samples for API endpoints.

## CLI

- [sourcey dev](/docs/cli/cli-dev): Start a Vite dev server with SSR hot reload.
- [sourcey build](/docs/cli/cli-build): Build static HTML documentation.
- [sourcey validate](/docs/cli/cli-validate): Validate an OpenAPI spec without building.

## Changelog

### 3.6.0 (2026-05-15)
Added: Source adapters as the primary tab configuration shape: source: markdown(...) , mkdocs(...) , openapi(...) , mcp(...) , doxygen(...) , and godoc(...) .
Added: mkdocs() source adapter for importing existing mkdocs.yml / mkdocs.yaml sites. Sourcey reads docs_dir , nav , and legacy pages , preserves explicit page labels, flattens nested MkDocs sections into Sourcey sidebar groups, expands snippets, normalizes admonitions/tabs, and carries static assets into the build.
Changed: sourcey init , first-party docs, examples, and 0state docs configs now use the adapter form. Legacy direct tab fields remain supported for existing projects.

### 3.5.10 (2026-05-10)
Fixed: Desktop sidebar scroll position now survives sidebar-initiated page navigation, so long generated docs sidebars no longer jump back to the top after selecting deep items in Doxygen/moxygen, OpenAPI, MCP, godoc, Markdown, or changelog tabs.
Fixed: Direct, search-result, and external deep links now reveal the active sidebar item without reusing stale sidebar state.

### 3.5.9 (2026-05-06)
Added: Native Go documentation as a fifth tab source ( godoc ). Sourcey extracts package docs directly from Go source via the toolchain ( go list + go/parser + go/doc ); no Doxygen pipeline. Supports live mode (runs Go at build time) and snapshot mode (reads a committed godoc.json ); mode: "auto" (default) picks live when Go is available and snapshot otherwise. Renders consts, vars, functions, types (struct, interface, alias, defined), fields with tags, methods, and examples from *_test.go .
Added: sourcey godoc --module . --packages './...' --out godoc.json CLI command to snapshot a Go module's documentation into a portable JSON artifact for JS-only docs hosts.
Added: Standalone sourcey-godoc Go module and CLI at github.com/sourcey/sourcey/go/sourcey-godoc/cmd/sourcey-godoc , with generate for static Go docs sites, snapshot for portable JSON, and cross-platform GitHub release binaries on go/sourcey-godoc/v* tags.
Added: goEnv option ( GOOS / GOARCH / tags ) for pinning the live-mode Go build environment so docs reproduce across hosts.
Added: includeTests , includeUnexported , hideUndocumented , and exclude options on godoc tabs.
Added: godoc package and symbol entries flow through the existing search index, llms.txt , llms-full.txt , and sitemap.xml pipelines.
Changed: Changelog page descriptions now render inline markdown so links and inline code resolve, with a constrained reading width and primary-tinted underlined links.
Changed: Unreleased version cards drop the dashed border for a primary-tinted left accent and soft tint, with a "Next release" pill in place of the empty meta row.
Fixed: Changelog parser no longer leaks bullet/paragraph tokens from non-SemVer headings into the page description, so trailing historical sections stop polluting the lead paragraph.

### 3.5.8 (2026-05-06)
Added: sourcey dev --host <address> flag (and HOST env var fallback) to control the Vite dev-server bind address. Defaults to 127.0.0.1 . Use --host 0.0.0.0 (or -e HOST=0.0.0.0 in Docker) to expose the dev server outside the host so the official sourcey/sourcey image's dev command works end-to-end.

### 3.5.6 (2026-05-05)
Fixed: Output-relative .html links between generated pages now resolve through the active prettyUrls mode, cleaning Doxygen body links such as icy.html#anchor when prettyUrls: "strip" is enabled.

### 3.5.5 (2026-05-05)
Fixed: Generated Doxygen page descriptions now render as plain text, preventing stale .html cross-reference links from appearing in page headers and metadata when prettyUrls: "strip" is enabled.

### 3.5.4 (2026-05-05)
Fixed: Generated Godoc and Doxygen tab navigation now normalizes through the active prettyUrls mode, so prettyUrls: "strip" builds do not emit stale .html or index.html navigation links.

### 3.5.3 (2026-05-05)
Fixed: prettyUrls: "strip" now emits foo.html files and public /foo links, without generated _redirects , so extensionless hosts do not loop between slashless and trailing-slash paths.
Fixed: Internal markdown links that still point at .html pages are rewritten to the active pretty URL form when they resolve to a generated page.

### 3.5.1 (2026-05-04)
Fixed: Sidebar nav and OpenAPI tab anchor base now honour prettyUrls ("slash" / "strip"). Previously hrefs were hard-coded to slug.html / tab/index.html , which 404 on hosts that don't auto-rewrite (e.g. GitHub Pages). Production sourcey.com masked the issue with its /foo.html → /foo/ 308 redirect.

### 3.5.0 (2026-04-24)
Added: OpenAPI 3.2 parsing and rendering for QUERY operations, response summaries, deviceAuthorization OAuth flows, hierarchical tags, querystring parameters, and media-type encoding metadata
Added: $self -aware reference resolution for canonical multi-document OpenAPI descriptions
Added: prettyUrls config option for clean URLs ( "slash" emits foo/index.html and links as /foo/ ; "strip" links as /foo and emits a _redirects file for static hosts that support redirect rules)
Changed: OG image template redesigned for legibility at Slack/Discord preview sizes: larger bold wordmark, vertical accent bar in theme primary, tighter type, single-grey description, no duplicate site-name footer
Fixed: Lint configuration for browser-side client scripts and generated MCP test artifacts

### 3.4.12 (2026-04-16)
Added: Automatic per-page OG image generation at build time using Satori and resvg
Added: ogImage config option for overriding with a static image URL
Added: Heroicons in navigation and UI components
Changed: Inter loaded as the default sans-serif; layout rhythm refined for tighter vertical spacing
Fixed: Tab path deduplication when multiple tabs share a slug
Fixed: Inline code styling inside TOC items
Fixed: TOC nested-item border alignment

### 3.4.5 (2026-04-07)
Added: Nested directives (e.g. tabs inside :::code-group )
Added: Doxygen link rewriting for cross-referenced symbols in prose
Fixed: Inline code protection during markdown directive preprocessing

### 3.4.4 (2026-04-06)
Fixed: OAuth security section rendering
Fixed: Footer logo restored after layout refactor
Fixed: Fenced markdown examples preserved through directive preprocessing

### 3.4.3 (2026-04-05)
Added: ::iframe directive for embedding arbitrary https URLs in markdown
Fixed: Doxygen page summaries now reuse resolved cross-links in page headers instead of exposing raw {#ref ... #} placeholders
Fixed: Rich Doxygen index cards strip inline markdown link syntax from summaries
Fixed: sourcey init now scaffolds projects against the latest published version again
Fixed: Minimal-theme callout borders and responsive page description sizing
Fixed: TOC sub-item margin alignment
Fixed: Search featured pages, inline dialog, display font, and sidebar dot markers
Fixed: Lighthouse baseline polish for generated docs

### 3.4.0 (2026-04-02)
Added: MCP server documentation as a first-class input format alongside OpenAPI, Markdown, and Doxygen
Added: mcp tab config option for rendering tools, resources, and prompts from an mcp.json snapshot
Added: Auto-generated code samples in JSON-RPC, TypeScript SDK, and Python SDK for all MCP operations
Added: Connection config card showing how to add the server to Claude, Cursor, or any MCP client
Added: Annotation badges for tool hints (read-only, destructive, idempotent, open-world)
Added: Colour-coded sidebar method pills (purple TOOL, green RES, blue PRMT)
Added: Hot-reload for mcp.json files in the dev server
Added: ::video directive for embedding YouTube, Vimeo, or raw video files in markdown
Added: Sitemap generation
Added: OpenGraph and Twitter Card meta tags
Added: Dockerfile for Docker Hub
Added: Nix flake support
Changed: Sidebar active state uses pill-style background instead of left border
Changed: Table of contents uses a continuous grey track with primary colour active marker
Changed: Clicking the first sidebar item scrolls to the top of the page
Fixed: Dev server fs.allow now includes the sourcey root for npm link compatibility
Fixed: Double-wrapped accordion groups from <AccordionGroup> component syntax

### 3.3.10 (2026-03-30)
Changed: Package metadata moved to sourcey.com and sourcey/sourcey org
Fixed: Node 24 JSON import compatibility

### 3.3.9 (2026-03-28)
Fixed: Page slugs preserve directory structure to avoid nav collisions

### 3.3.8 (2026-03-28)
Fixed: slugFromPath preserves directory structure

### 3.3.7 (2026-03-27)
Added: Relative source links in markdown rewrite to repo URLs at build time

### 3.3.6 (2026-03-27)
Added: Doxygen index page generation
Fixed: Doxygen index content links

### 3.3.5 (2026-03-26)
Fixed: CLI help output reports the actual package version
Fixed: sourcey init scaffolds new projects with the latest published version

### 3.3.4 (2026-03-26)
Changed: First page renders directly instead of meta-refresh redirect

### 3.3.2 (2026-03-25)
Added: sourcey init auto-detects project type and offers directory selection
Added: Init reads Doxygen XML_OUTPUT for proper path resolution

### 3.3.1 (2026-03-25)
Fixed: Use jiti for TypeScript config loading
Fixed: Resolve moxygen from npm registry

### 3.3.0 (2026-03-25)
Added: sourcey init command for scaffolding new projects
Added: Scroll tracker ?target query parameter for deep linking
Added: Node 24 in CI test matrix

### 3.2.1 (2026-03-24)
Fixed: Dev server asset path resolution for npm installs

### 3.2.0 (2026-03-23)
Added: Internal link resolution between markdown pages
Added: editBasePath config option for repos with docs in a subdirectory
Added: Previous/next page navigation at the bottom of markdown pages
Added: Brand icons (GitHub, npm, etc.) in navbar and footer

### 3.1.0 (2026-03-22)
Added: Mobile navigation drawer with breadcrumbs
Added: Configurable tab slugs
Added: Collapsible schemas in API reference
Added: "Edit this page" links on markdown pages
Added: Auto Google Fonts loading from theme config
Changed: Stone-palette code surfaces
Changed: TOC nesting improvements
Fixed: Responsive layout at small breakpoints
Fixed: Code indent rendering
Fixed: Dev server error recovery
Fixed: Sidebar active state on prose pages
Fixed: Duplicate h1 headings
Fixed: Logo paths resolve relative to config directory

### 3.0.2 (2026-03-21)
Added: Geist Mono as default monospace font
Changed: Config changes hot-reload in dev server
Fixed: Scroll offset calculation

### 3.0.1 (2026-03-21)
Added: Doxygen C++ documentation via Moxygen integration
Added: Command palette search (Cmd+K)
Added: Google Fonts loading and font stack configuration
Fixed: Moxygen resolved from npm registry
Fixed: TOC scroll tracking
Fixed: Heading scroll offset

### 3.0.0 (2026-03-20)
Added: Redesigned theme with new layout, typography, and colour system
Added: Theme presets (default, minimal, api-first) with custom colours, fonts, and layout
Added: EndpointBar component with colour-coded method badges
Added: CopyButton and SocialIcon UI components
Added: Demo site with markdown guides
Added: Unified Vite plugin for dev server
Changed: Renamed from spectacle-docs to sourcey
Changed: License changed from MIT to AGPL-3.0-only
Changed: Complete redesign of Header, Sidebar, Page, TableOfContents, CodeSamples, Responses, and Security components
Removed: Legacy Handlebars/Foundation/SCSS theme
Removed: TabBar and old CodeBlock components

### 2.1.0 (2026-03-19)
Added: Multi-page sites with tabbed navigation and sidebar groups
Added: Markdown pages with rich components (Steps, Cards, Accordions)
Added: Vite dev server with SSR hot reload
Added: Header with navbar links and CTA button
Added: Table of contents with scroll tracking
Added: Footer with social links
Added: Cross-page navigation link resolution
Changed: Dark example panel hidden on prose-only pages

### 2.0.2 (2026-03-19)
Added: Vite dev server with header, TOC, and layout system

### 2.0.0 (2026-03-10)
Added: TypeScript codebase with Preact SSR
Added: sourcey.config.ts with defineConfig() and full type safety
Added: OpenAPI 3.x support (auto-converts Swagger 2.0)
Added: Shiki syntax highlighting
Added: Dark mode with localStorage persistence
Added: Client-side search with keyboard navigation (Cmd+K)
Added: Auto-generated code samples in 10 languages
Added: Custom colour theming with hex-to-RGB token system
Added: Stone-palette code blocks with language dropdown and response tabs
Added: Copy button on code blocks
Added: Scroll-tracked sidebar navigation
Added: Enum pills and array item type display
Added: Logo support with light/dark variants
Added: Static HTML output with no framework runtime
Added: GitHub Actions CI
Removed: Handlebars template engine
Removed: Grunt build system
Removed: highlight.js

### 1.1.0 (2020-03-10)
Fixed: Example rendering
Fixed: Dependency vulnerabilities (handlebars, js-yaml, lodash, marked, fstream)

### 1.0.7 (2019-01-30)
Added: YAML example support
Fixed: Href with colon characters
Fixed: Href with multiple dots
Fixed: Code block overflow

### 1.0.6 (2018-09-20)
Changed: Licence update

### 1.0.5 (2018-07-02)
Changed: Updated Grunt dependencies

### 1.0.4 (2018-07-01)
Fixed: grunt-sass 3.0 compatibility
Fixed: grunt-sass dependency resolution

### 1.0.3 (2018-04-15)
Added: Nested objects and arrays in definitions
Added: Resource embedding support
Added: Enum definition descriptions
Added: $ref support in parameters and responses
Added: Development mode with live reload
Added: Schema syntax error reporting in dev mode
Added: x-nullable support

### 1.0.2 (2018-03-22)
Changed: Security partial rendering

### 1.0.1 (2018-03-21)
Fixed: Markdown rendering (#122, #126)
Fixed: Schema description rendering and linking

### 1.0.0 (2018-03-20)
Added: Quiet output option
Fixed: Remote file reference rendering

### 0.9.12 (2017-11-13)
Added: Response header display
Fixed: Null node error in reference resolution

### 0.9.11 (2017-10-13)
Fixed: Null check in reference replacement

### 0.9.10 (2017-09-27)
Fixed: Remote reference tests

### 0.9.9 (2017-09-27)
Added: Min/max range display for parameters
Added: maxLength and minLength display for strings
Added: Better rendering of arrays of objects

### 0.9.8 (2017-09-01)
Fixed: Rendering on large screens with indents

### 0.7.0 (2017-02-01)
Added: Programmatic API with promise return

### 0.6.9 (2017-01-16)
Added: Remote schema support
Added: Temporary directory per build run

### 0.6.8 (2017-01-13)
Fixed: Code highlighting
Fixed: HTTPS for jQuery reference

### 0.5.0 (2016-12-31)
Added: OpenAPI 2.0 (Swagger) rendering
Added: Foundation 6 responsive layout with drawer navigation
Added: Custom logo support
Added: Docker support
Added: Recursive example parsing
Added: Definition rendering with JSON examples
Added: Custom CSS scoping
Added: Handlebars template engine