Skip to content

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.

bash
npm init -y
npm install -D vitepress

Create docs/.vitepress/config.mjs and enable extensionless URLs.

js
import { defineConfig } from "vitepress";

export default defineConfig({ title: "My Docs", cleanUrls: true });

Create docs/index.md.

md
# My documentation

[Quickstart](./guide/start)

Create docs/guide/start.md.

md
# Quickstart

This page can be opened directly.

Build and start the preview from the project root.

bash
npx vitepress build docs
npx vitepress preview docs --host 127.0.0.1 --port 4173

Open 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.

nginx
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.