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

# holydocs dev

Start the local HolyDocs preview server with hot reload.

## Usage

```bash
holydocs dev [options]
```

Starts a local HTTP server that renders your docs with the same pipeline used by the production renderer. Changes to MDX files, snippets, custom components, OpenAPI specs, and config files trigger reloads automatically.

## Options

| Option | Description | Default |
|---|---|---|
| `--port <number>` | Port for the local dev server | `3333` |
| `--dir <path>` | Project directory containing `docs.json`, `docs.yaml`, `docs.yml`, or `mint.json` | Current directory / nearest project root |

## Examples

### Basic Usage

```bash
holydocs dev
```

Output:

```
  HolyDocs Dev Server

  Project: My Docs
  Theme:   mint
  Config:  /path/to/docs.json

✓ Server running at http://localhost:3333
  Watching for changes...
```

### Custom Port

```bash
holydocs dev --port 8080
```

### Run from a Specific Directory

```bash
holydocs dev --dir ./docs
```

## What It Watches

The dev server watches:

- `*.mdx` and `*.md` pages
- `docs.json`, `docs.yaml`, `docs.yml`, or `mint.json`
- `_snippets/`
- `_components/`
- `openapi.json`, `openapi.yaml`, `openapi.yml`, `swagger.json`, `swagger.yaml`, `swagger.yml`

## Feature Parity

The local preview uses the real HolyDocs renderer pipeline, including:

- MDX rendering and built-in components
- Theme CSS generation
- Navigation rendering
- Snippet expansion
- Custom components
- OpenAPI reference page rendering

Some cloud-backed features are still production-only:

| Feature | Local Dev | Production |
|---|---|---|
| MDX rendering | Yes | Yes |
| Navigation and theme | Yes | Yes |
| OpenAPI reference pages | Yes | Yes |
| AI assistant | No | Yes |
| AI search | No | Yes |
| Analytics | No | Yes |
| Custom domains | No | Yes |

## Troubleshooting

### Port Already in Use

If port 3333 is occupied:

```bash
holydocs dev --port 3001
```

### No Config Found

If the CLI cannot find `docs.json` or `mint.json`, initialize a project first:

```bash
holydocs init
```

### Hot Reload Seems Stuck

If a change does not appear:

1. Make sure the file lives inside the project root
2. Check the terminal for parse errors
3. Restart `holydocs dev`

Use [`holydocs check`](/cli/check) if the preview fails after a config change. It surfaces config mistakes more directly than the rendered error page.