Deployment
A VitePress build produces a directory of static files, so publishing it is not a deployment problem so much as a file-copying problem. Most of the work is in the details that are easy to forget: the base path, the cache headers, and the directory the host is told to serve. This page covers those in order.
The build and preview commands are the same ones you have been using during development:
npm run docs:build
npm run docs:preview
The build writes to docs/.vitepress/dist by default, and the preview command serves that directory on http://localhost:4173. Always preview the production build before publishing: the dev server renders pages on demand and is lenient, while the build pre-renders every page and fails on a dead internal link, so the preview is where those failures show up. The port can be changed with --port.
The default scripts assume the source directory is docs:
{
"scripts": {
"docs:build": "vitepress build docs",
"docs:preview": "vitepress preview docs"
}
}
By default the site assumes it will be served from the root of a domain. If it will live under a sub-path — a GitHub Pages project site, for instance, is served from the repository name — you must tell the generator, or every asset URL and internal link will point at the wrong place:
export default defineConfig({
base: '/my-repo/'
})
The value must start and end with a slash. The base is prepended automatically to every absolute path in the other options, so you set it once rather than in the navigation, the sidebar, and the images separately.
The production build writes content-hashed filenames for JavaScript, CSS, and imported assets — a file like app.4f283b18.js is guaranteed to contain the same bytes every time that URL is requested, because the hash is derived from the content. That makes it safe to cache those files indefinitely, and worth doing, because it is the difference between a repeat visitor downloading the site again and a repeat visitor downloading nothing.
The hashed files are written to an assets directory inside the output, so a host that lets you set headers by path should be told to treat that directory as immutable:
Cache-Control: max-age=31536000,immutable
On Netlify this is a _headers file in the public directory, which is copied verbatim into the output:
# docs/public/_headers
/assets/*
cache-control: max-age=31536000
cache-control: immutable
On Vercel it belongs in a vercel.json at the root of the repository:
{
"headers": [
{
"source": "/assets/(.*)",
"headers": [
{
"key": "Cache-Control",
"value": "max-age=31536000, immutable"
}
]
}
]
}
For the hosted platforms that accept a build command and an output directory — Netlify, Vercel, Cloudflare Pages, Azure Static Web Apps, Render — the configuration is the same three values:
| Setting | Value |
|---|---|
| Build command | npm run docs:build |
| Output directory | docs/.vitepress/dist |
| Node version | A current Node.js release |
If you enable cleanUrls so that URLs drop their .html suffix, your host has to be able to serve /foo.html when a request comes in for /foo, without redirecting. Not every host does this out of the box, so check it after enabling the option.
One warning that applies to every host: do not enable aggressive HTML minification. The minifier removes comments, and the Vue runtime uses HTML comments as hydration markers, so stripping them causes hydration mismatch errors in the browser. If a host offers the option, leave it off.
GitHub Pages is deployed from a workflow in the repository. Create .github/workflows/deploy.yml:
name: Deploy VitePress site to Pages
on:
push:
branches: [main]
workflow_dispatch:
permissions:
contents: read
pages: write
id-token: write
concurrency:
group: pages
cancel-in-progress: false
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Setup Node
uses: actions/setup-node@v4
with:
node-version: 22
cache: npm
- name: Setup Pages
uses: actions/configure-pages@v4
- name: Install dependencies
run: npm ci
- name: Build with VitePress
run: npm run docs:build
- name: Upload artifact
uses: actions/upload-pages-artifact@v3
with:
path: docs/.vitepress/dist
deploy:
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
needs: build
runs-on: ubuntu-latest
steps:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v4
Then, in the repository settings, set the Pages build source to “GitHub Actions” rather than to a branch. Every push to the configured branch now rebuilds and republishes the site.
For a project site served from https://<user>.github.io/<repo>/, remember to set base: '/<repo>/' in the configuration. The fetch-depth: 0 option on the checkout step is only needed if you have enabled lastUpdated, because that feature reads the commit history from Git.
The build output is just a directory, so most hosts need only a path.
GitLab Pages publishes from a public directory at the root of the repository, so point the output there and add a pipeline file:
export default defineConfig({
outDir: '../public',
base: '/my-repo/'
})
# .gitlab-ci.yml
image: node:22
pages:
cache:
paths:
- node_modules/
script:
- npm install
- npm run docs:build
artifacts:
paths:
- public
only:
- main
Firebase Hosting takes a firebase.json in the repository root:
{
"hosting": {
"public": "docs/.vitepress/dist",
"ignore": []
}
}
and is published with firebase deploy after the build. Surge needs nothing but the directory:
npx surge docs/.vitepress/dist
Azure Static Web Apps uses three values in its configuration file: app_location set to /, output_location set to docs/.vitepress/dist, and app_build_command set to npm run docs:build.
If you run your own server, the only requirement is that it serves the output directory and can apply the cache headers described above. When cleanUrls is enabled, the server also needs to resolve a request for /foo to the file foo.html.
Before the first deploy, confirm that the base option matches the path the site will actually be served from, that the output directory in the host settings points at docs/.vitepress/dist, that the cache headers cover the assets directory, and that HTML minification is disabled. Then run the build locally, preview it, and check the links on a handful of pages — particularly the ones that cross section boundaries, since those are the ones that expose a wrong base path.
A useful last step is to enable lastUpdated and confirm it renders, because that option depends on the full Git history being available during the build, and a shallow checkout in CI is the usual reason it comes out empty.
Once the site is live, the remaining work is content, and the pipeline itself will not need attention again unless the hosting target changes.
