> ## Documentation Index
> Fetch the complete documentation index at: https://docs.superworker.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Documentation development

> Preview, validate, and publish the Superworker Mintlify site.

## Preview locally

From the repository root:

```bash theme={null}
pnpm docs:dev
```

Open `http://localhost:3002`. Mintlify reloads the preview as you edit. The first
run downloads the pinned CLI and its preview dependencies, so it needs network
access. Local preview and validation do not require a Mintlify account.
Mintlify search requires signing in with the CLI.

The configuration is the repository-root `docs.json`, and pages live in `apps/docs`.
The root `.mintignore` limits publishing to the site files. Internal planning and
research documents in `docs` are excluded from the published site.

## Add a page

Create an MDX file beneath `apps/docs` with a title and description:

```mdx theme={null}
---
title: 'Your guide'
description: 'What the reader will learn.'
---

Write your guide here.
```

Add its path to a group in `docs.json` without the `.mdx` extension. For example,
`apps/docs/guides/your-guide.mdx` becomes `apps/docs/guides/your-guide` in navigation.
Link to pages using root-relative paths, such as `/apps/docs/quickstart`.

Use built-in Mintlify components for layout. The site uses Superworker's plain
text name, white canvas, majorelle accents, Montserrat text, and JetBrains Mono
code. Change site-wide branding in the root `docs.json` and shared styling in the
root `style.css`.

## Validate changes

```bash theme={null}
pnpm docs:check
```

This runs Mintlify's build validation followed by its internal link checker. To
run either check separately:

```bash theme={null}
pnpm docs:validate
pnpm docs:links
```

Keep examples aligned with the implementation. Describe planned behavior as
planned, and distinguish saved-result reads from actions that start new work.

## Connect Mintlify for publishing

This step requires a Mintlify sign-in and access to connect the GitHub repository.

1. Sign in to the [Mintlify dashboard](https://app.mintlify.com).
2. Connect `superworker-ai/mcp` through the Mintlify GitHub app.
3. Select `main` as the deployment branch.
4. Keep **docs.json is in a subdirectory** disabled. The configuration is at the
   repository root, so leave the documentation subdirectory empty.
5. Save the configuration and review the deployment once the docs are on `main`.

Mintlify hosts the site separately from the Superworker applications. Configure
the published URL or a custom domain in Mintlify after connecting the repository.

See Mintlify's [monorepo deployment guide](https://www.mintlify.com/docs/deploy/monorepo)
and [CLI reference](https://www.mintlify.com/docs/cli/commands) for platform details.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.