Deploy the documentation site
Build a small VitePress site with a home page and a nested page to try static deployment. Publish the entire docs/.vitepress/dist directory to your static host.
Build and preview
Initialize an npm project and install VitePress in an empty directory.
npm init -y
npm install -D vitepressCreate docs/.vitepress/config.mjs and enable extensionless URLs.
import { defineConfig } from "vitepress";
export default defineConfig({ title: "My Docs", cleanUrls: true });Create docs/index.md.
# My documentation
[Quickstart](./guide/start)Create docs/guide/start.md.
# Quickstart
This page can be opened directly.Build and start the preview from the project root.
npx vitepress build docs
npx vitepress preview docs --host 127.0.0.1 --port 4173Open http://127.0.0.1:4173/ and follow Quickstart. Open http://127.0.0.1:4173/guide/start in a new tab and reload it. Both paths should show the Quickstart heading.
Nginx
Add the routing and cache rules below to the site's server block, keeping its port, TLS, and logging settings.
The root must contain the full build output. Load mime.types in the Nginx http block so scripts and styles receive the correct MIME types.
location / {
try_files $uri $uri.html $uri/ =404;
add_header Cache-Control "no-cache" always;
}
location ^~ /assets/ {
try_files $uri =404;
add_header Cache-Control "public, max-age=31536000, immutable";
}
location = /hashmap.json {
try_files $uri =404;
add_header Cache-Control "no-cache" always;
}/guide/start should serve guide/start.html, and / should serve index.html. Missing pages and resources return 404.
Do not use try_files $uri $uri/ /index.html or rewrite every 404 to the home page. A conventional Vue SPA fallback serves the wrong prerendered page to deep URLs and can leave VitePress in an invalid page state.
Run nginx -t after editing the configuration, then nginx -s reload only after validation succeeds. These are deployment operations; building the source does not change the server.
Files and caching
Publish HTML, assets/, hashmap.json and other static files from the same build. Do not use long-lived immutable caching for HTML or hashmap.json. Content-hashed assets can be cached long term. Apply the same routing and cache rules at any CDN, and never rewrite a missing script to HTML.
Do not let additional CDN HTML minification remove Vue's comment nodes. Invalidate old HTML and hashmap.json after deployment so pages do not keep referencing unavailable assets.
Verify the deployment
Open /guide/start directly on the deployed domain and reload. Confirm that the heading is Quickstart. Check the script and stylesheet response types in the browser's Network panel. Then request a missing page and asset, such as /missing-page and /assets/missing.js. Both should return 404.
Other static hosts
Publish docs/.vitepress/dist. With cleanUrls: true, the host must map extensionless URLs to their corresponding HTML files.
A dedicated domain uses the default root base. For a subdirectory deployment, build with npx vitepress build docs --base /docs/ and configure the static host's directory mapping accordingly.
