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.

Build and check locally

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

Set the base path

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.

Cache headers

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"
        }
      ]
    }
  ]
}

Platform settings

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:

SettingValue
Build commandnpm run docs:build
Output directorydocs/.vitepress/dist
Node versionA 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

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.

Other hosts

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.

A publishing checklist

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.

Found an issue with this content?

Tell us what could be improved.