Quick Start — Sourcey

This guide walks through creating a documentation site with an API reference and markdown pages. You'll have a working site running locally in under a minute.

Prerequisites

Node.js 20 or later
An OpenAPI spec or MCP server snapshot (optional; you can start with markdown-only)

Get started

npx sourcey init
npm install
npx sourcey dev

The init command is interactive. It prompts for a project name and theme preset, and auto-detects any OpenAPI specs or Doxyfiles in your directory. When it finishes you'll have a sourcey.config.ts, example pages, a package.json with dev/build scripts, and a .gitignore.

If you're inside an existing project it suggests a docs/ subdirectory so your docs live alongside your source.

Install sourcey as a dependency:

npm install sourcey

Also available via pnpm (pnpm add sourcey), yarn, Homebrew (brew tap sourcey/sourcey && brew install sourcey), Docker, or Nix.

Then create your config and first page manually — see below.

The config

Every sourcey project starts with a sourcey.config.ts in the project root. This file declares your site structure: tabs, groups, and which pages belong where. If you used init, this was created for you.

// sourcey.config.ts
import { defineConfig } from "sourcey";

export default defineConfig({
  name: "My Project",
  theme: {
    colors: {
      primary: "#0066cc",
    },
  },
  navigation: {
    tabs: [
      {
        tab: "Documentation",
        slug: "",
        groups: [
          {
            group: "Getting Started",
            pages: ["introduction", "quickstart"],
          },
        ],
      },
      {
        tab: "API Reference",
        slug: "api",
        openapi: "./openapi.yaml",
      },
    ],
  },
});

Note

All file paths in the config are relative to the directory containing sourcey.config.ts. Sourcey looks for this file in your current working directory.

Write your first page

Create a markdown file for each page referenced in your config. The filename (without extension) must match the slug in the pages array.

---
title: Introduction
description: Welcome to our documentation.
---

This is your first documentation page. Write standard markdown here.

## Features

- OpenAPI reference generation
- Markdown guides with rich components
- Client-side search
- Dark mode

Start the dev server

npx sourcey dev

This starts a Vite-powered dev server on port 4400 with hot reload. Edit your markdown or config and the page updates instantly.

Build for production

npx sourcey build

This writes static HTML to dist/. Every page is a standalone HTML file with inlined styles. No framework runtime ships to the browser.

Sourcey - building documentation site

  Pages:  4
  Output: dist
  Time:   0.8s

Deploy the dist/ directory to GitHub Pages, Vercel, Netlify, S3, or any static file host.

Tip

Already have an OpenAPI spec? Skip the config entirely: sourcey build api.yaml generates a complete API reference from a single file.

Next steps

Project Structure

How sourcey resolves pages, specs, and output.

Components

Rich directives for steps, tabs, cards, callouts, and more.

Cheese Store Demo

A complete reference project with multi-tab navigation, OpenAPI integration, and every component type. Clone it and run sourcey dev.