Your First Docs Site

This tutorial builds a documentation site for a fictional "Tasks API" with markdown guides and an auto-generated API reference. By the end, you'll have a multi-tab site with navigation, search, and dark mode.

What we're building

A docs site with two tabs:

Documentation - an introduction page and a quickstart guide
API Reference - auto-generated from an OpenAPI spec

Note

This tutorial takes about 15 minutes. If you just want to see the minimal setup, the Quick Start page covers the essentials in under 5 minutes.

Setup

Create the project directory

mkdir tasks-docs && cd tasks-docs
npm init -y
npm install sourcey

Create the config

Create sourcey.config.ts in the project root:

import { defineConfig } from "sourcey";

export default defineConfig({
  name: "Tasks API",
  theme: {
    colors: {
      primary: "#6366f1",
    },
  },
  navigation: {
    tabs: [
      {
        tab: "Documentation",
        slug: "",
        groups: [
          {
            group: "Getting Started",
            pages: ["introduction", "quickstart"],
          },
        ],
      },
      {
        tab: "API Reference",
        slug: "api",
        openapi: "./openapi.yaml",
      },
    ],
  },
  navbar: {
    links: [
      { type: "github", href: "https://github.com/your-org/tasks-api" },
    ],
  },
});

Write the introduction page

Create introduction.md:

---
title: Introduction
description: The Tasks API lets you create, manage, and track tasks programmatically.
---

The Tasks API is a REST API for task management. Authenticate with an API key, make requests, get JSON responses.

## Features

:::card-group{cols="2"}
::card{title="Task Management" icon="book"}
Create, update, delete, and list tasks. Assign priorities, due dates, and labels.
::
::card{title="Webhooks" icon="bell"}
Get notified when tasks are created, completed, or overdue.
::
:::

Write the quickstart page

Create quickstart.md:

---
title: Quick Start
description: Make your first API request in under a minute.
---

:::steps
1. Get an API key
   Sign up at the dashboard and copy your API key.
2. Create a task
   ```bash
   curl -X POST https://api.tasks.dev/v1/tasks \
     -H "Authorization: Bearer YOUR_KEY" \
     -H "Content-Type: application/json" \
     -d '{"title": "Ship the docs", "priority": "high"}'
   ```
3. Verify it worked
   ```bash
   curl https://api.tasks.dev/v1/tasks \
     -H "Authorization: Bearer YOUR_KEY"
   ```
:::

Add an OpenAPI spec

Create openapi.yaml with your API spec. If you don't have one yet, you can use any valid OpenAPI 3.x file to test the setup.

Start the dev server

npx sourcey dev

Open http://localhost:4400. You should see your docs with sidebar navigation, a table of contents, and working search.

Build for production

npx sourcey build

The dist/ directory contains your complete site. Deploy it anywhere.

What to do next

Add more pages by creating markdown files and referencing them in the config
Customize the theme with your brand colors and logo
Set up repo and editBranch in the config to enable "Edit this page" links
Configure codeSamples to control which languages appear in the API reference

Tip

Want a more complete reference? The Cheese Store demo is a production-quality sourcey project with four tabs, markdown guides, an OpenAPI-generated API reference, custom branding, and every component type. Clone it and use it as a starting point: git clone https://github.com/cheesestore/docs && cd docs && npm install && npx sourcey dev.