holydocs dev

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:

text
  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 if the preview fails after a config change. It surfaces config mistakes more directly than the rendered error page.