# Deploy VitePress on Lizard

Lizard can build a VitePress documentation site and serve the generated HTML through nginx on port `80`. Match the npm script and output directory to your docs root: `vitepress build docs` writes `docs/.vitepress/dist`, while `vitepress build` writes `.vitepress/dist`.

Start with the [complete source example](https://github.com/lizard-build/docs/tree/main/_examples/vitepress), which includes the configuration and files used by this recipe.

## Set the build script

For Markdown files in `docs/`, keep these scripts in `package.json`:

```json
{
  "scripts": {
    "docs:dev": "vitepress dev docs",
    "docs:build": "vitepress build docs",
    "docs:preview": "vitepress preview docs"
  }
}
```

| Setting | Value in this guide |
|---|---|
| Build | `npm run docs:build` |
| Docs root | `docs/` |
| Output | `docs/.vitepress/dist/` |
| Production server | nginx |
| Service port | `80` |

The detector finds a script containing `vitepress build` and uses its root argument. Keep that script direct and unambiguous. Shell wrappers, several matching scripts, or a custom `outDir` need explicit build configuration or a Dockerfile.

## Check the site locally

```bash
npm ci
npm run docs:build
npm run docs:preview
```

Check an inner Markdown page and an asset. With `cleanUrls: true`, VitePress links to extensionless routes; the production server must resolve those URLs to the generated HTML files. Set `base` to the actual path prefix, or `/` for the domain root. See [VitePress deployment](https://vitepress.dev/guide/deploy).

## Deploy

After [CLI setup](https://lizard.build/docs/framework-guides#prepare-the-project), run from the directory containing `package.json`, not from inside `docs/`:

```bash
lizard init --name vitepress-docs
lizard add --service web
lizard up --service web --port 80
lizard logs --build --service web --json
lizard ps --json
```

Include the VitePress config, Markdown, source assets, package manifest, and lockfile. Exclude local dependencies, generated output, caches, and secrets. Do not set `vitepress dev` or `vitepress preview` as the service start command.

## Check clean routes and HTTP status

New VitePress builds resolve extensionless routes to their generated `.html` files and return HTTP 404 for missing URLs. Keep command overrides unset to use this detection path. No custom Dockerfile is needed for the standard output. See [static routes and 404s](https://lizard.build/docs/framework-guides/static-routing) for custom routing.

Check a clean URL directly and reload it. Request a path that does not exist and confirm HTTP 404. If an older image serves the home page for missing paths, rebuild the service to pick up the current routing rules.

If the build reports `Missing script: build`, check that the selected path uses the VitePress detector and that no service command override replaces it. If the build succeeds but nginx serves no docs, compare the script's docs root with the copied output directory. Rebuild after content or configuration changes.

See [tested versions and cloud results](https://lizard.build/docs/framework-guides/validation) for the September 9, 2026 deployment checks and their limits.