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, 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:

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

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

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.

Deploy

After CLI setup, run from the directory containing package.json, not from inside docs/:

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 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 for the September 9, 2026 deployment checks and their limits.

Updated September 9, 2026