Deploy the documentation site

Fast.Docs uses VitePress to generate HTML for each page, together with CSS and JavaScript. Deploy the complete docs/.vitepress/dist directory, not the source directory or only the root index.html.

Build and preview

pnpm install --frozen-lockfile
pnpm run build
pnpm run preview

Open http://localhost:4173/en-US/frontend/utils/runtime-contract directly and reload it. Client-side navigation from the home page alone is not a deployment test.

Nginx

The repository includes a complete server example at deploy/nginx.conf. Merge its routing and cache rules into the existing server for the domain, retaining the deployment's root, ports, TLS and logging configuration. Do not create competing server blocks for the same domain.

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;
}

/en-US/frontend/utils/runtime-contract must serve en-US/frontend/utils/runtime-contract.html. Directory URLs serve their own 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

pnpm run check:deployment -- http://docs.fastdotnet.cn/

The checker makes read-only requests. It verifies the identity of directly requested Chinese and English HTML pages, repeated requests, script/style MIME types, and HTTP 404 for missing pages and assets. Deploy this build first: its fast-docs-page metadata identifies the HTML that was actually returned.

Also reload and navigate in a browser while checking Console and Network. HTTP 200 alone is not enough. A home-page response for a deep URL, or a script returned as text/html, indicates incorrect routing or inconsistent deployment output.

Other static hosts

Use pnpm install --frozen-lockfile, build with pnpm run build, and publish docs/.vitepress/dist. With cleanUrls: true, the host must map extensionless URLs to their corresponding HTML files, not to a SPA fallback.

A dedicated domain uses the default root base. For a subdirectory deployment, build with pnpm run build --base /docs/ and configure the static host's directory mapping accordingly.