Deploying Your VitePress Site

VitePress generates static HTML files that can be deployed to any hosting platform. This guide covers building for production and deploying to popular platforms.

Prerequisites

These deployment guides assume:

VitePress site is in the docs directory
Using default build output directory (.vitepress/dist)
VitePress installed as a local dependency
npm scripts configured in package.json:

package.json

{
  "scripts": {
    "docs:build": "vitepress build docs",
    "docs:preview": "vitepress preview docs"
  }
}

Build and Test Locally

Build your site

Generate static HTML for production:

npm run docs:build

Built files are output to .vitepress/dist.

Preview locally

Test the production build before deploying:

npm run docs:preview

The preview server runs at http://localhost:4173.

Configure port (optional)

Change the preview server port:

package.json

{
  "scripts": {
    "docs:preview": "vitepress preview docs --port 8080"
  }
}

Setting a Public Base Path

If your site is served from a subdirectory, set the base option:

.vitepress/config.js

export default {
  base: '/blog/'  // For https://mywebsite.com/blog/
}

GitHub Pages example: Deploying to user.github.io/repo/ requires base: '/repo/'

HTTP Cache Headers

Optimize performance with proper cache headers for static assets.

Understanding Asset Hashing

VitePress uses content-based hashing for assets:

app.4f283b18.js
     ^^^^^^^^ content hash

The hash changes only when file content changes, enabling aggressive caching.

Recommended Cache Headers

For files in the assets/ directory:

Cache-Control: max-age=31536000,immutable

Netlify
Vercel
Nginx

Create docs/public/_headers:

_headers

/assets/*
  cache-control: max-age=31536000
  cache-control: immutable

The _headers file in the public directory is copied to the build output.

Netlify headers documentation

Create vercel.json in your repository root:

vercel.json

{
  "headers": [
    {
      "source": "/assets/(.*)",
      "headers": [
        {
          "key": "Cache-Control",
          "value": "max-age=31536000, immutable"
        }
      ]
    }
  ]
}

Vercel headers documentation

Add to your server block configuration:

location ~* ^/assets/ {
    expires 1y;
    add_header Cache-Control "public, immutable";
}

Platform-Specific Guides

Netlify / Vercel / Cloudflare Pages / AWS Amplify / Render

These platforms work similarly - configure via dashboard:

Connect repository

Link your Git repository to the platform.

Configure build settings

Build Command: npm run docs:build
Output Directory: docs/.vitepress/dist
Node Version: 20 (or above)

Deploy

Push to your main branch to trigger deployment.

Don’t enable Auto Minify for HTML. It removes Vue-specific comments and causes hydration errors.

GitHub Pages

Deploy automatically using GitHub Actions:

Create workflow file

Create .github/workflows/deploy.yml:

.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@v5
        with:
          fetch-depth: 0
      
      - name: Setup Node
        uses: actions/setup-node@v6
        with:
          node-version: 24
          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
    name: Deploy
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

Configure Pages source

In repository settings under Pages, set:

Source: GitHub Actions

Set base path

Update .vitepress/config.js:

export default {
  base: '/repository-name/'
}

Deploy

Push to main branch. Your site deploys to:https://username.github.io/repository/

For pnpm or yarn, uncomment the relevant sections in the workflow file and update the cache and install commands.

GitLab Pages

Deploy using GitLab CI:

Configure output directory

GitLab Pages requires output in public/:

.vitepress/config.js

export default {
  outDir: '../public',
  base: '/repository/'  // For project pages
}

Omit base for user/group pages or custom domains.

Create CI configuration

Create .gitlab-ci.yml in repository root:

.gitlab-ci.yml

image: node:18

pages:
  cache:
    paths:
      - node_modules/
  
  script:
    - npm install
    - npm run docs:build
  
  artifacts:
    paths:
      - public
  
  only:
    - main

Deploy

Push to the main branch to trigger the pipeline.

Azure Static Web Apps

Follow Azure documentation

See the official Azure Static Web Apps guide.

Configure build settings

Set these values in your configuration:

app_location: /
output_location: docs/.vitepress/dist
app_build_command: npm run docs:build

Firebase

Create Firebase config

Create firebase.json and .firebaserc in your repository root:

firebase.json

{
  "hosting": {
    "public": "docs/.vitepress/dist",
    "ignore": []
  }
}

.firebaserc

{
  "projects": {
    "default": "YOUR_FIREBASE_ID"
  }
}

Build and deploy

npm run docs:build
firebase deploy

Surge

Quick deployment with Surge:

npm run docs:build
npx surge docs/.vitepress/dist

Custom Nginx Server

Example Nginx configuration with gzip compression and proper caching:

server {
    gzip on;
    gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;
    
    listen 80;
    server_name _;
    index index.html;
    
    location / {
        # Content location
        root /app;
        
        # Exact matches -> reverse clean urls -> folders -> not found
        try_files $uri $uri.html $uri/ =404;
        
        # Non-existent pages
        error_page 404 /404.html;
        
        # Folder without index.html raises 403
        error_page 403 /404.html;
        
        # Cache headers for hashed assets
        location ~* ^/assets/ {
            expires 1y;
            add_header Cache-Control "public, immutable";
        }
    }
}

Important: Do not default try_files to index.html like in SPAs. This causes invalid page state in VitePress.

This assumes your built site is in /app. Adjust the root directive for your setup.

Additional Platforms

CloudRay

Deploy with CloudRay - follow their VitePress guide

Hostinger

Deploy to Hostinger - see their deployment guide

Kinsta

Deploy to Kinsta - follow their VitePress example

Stormkit

Deploy to Stormkit - see their deployment guide

Build Options

Customize the build process with command-line options:

Output Directory

Change the build output location:

vitepress build docs --outDir ./dist

Or in config:

.vitepress/config.js

export default {
  outDir: './dist'
}

Base Path at Build Time

Override the base path during build:

vitepress build docs --base /new-base/

MPA Mode

Build as a traditional multi-page application (disables client-side routing):

vitepress build docs --mpa

Or in config:

.vitepress/config.js

export default {
  mpa: true
}

Troubleshooting

Build Fails on CI

Ensure Node.js version 18 or higher:

- uses: actions/setup-node@v6
  with:
    node-version: 24

404 on Deployment

Check your base path configuration matches your hosting setup:

Root domain: base: '/' (default)
Subdirectory: base: '/subdirectory/'

Assets Not Loading

Verify:

Base path includes trailing slash: base: '/repo/' not '/repo'
Assets are in docs/public/ or imported in components
Cache headers are properly configured

Clean URLs Not Working

Enable clean URL support on your hosting platform or disable in config:

.vitepress/config.js

export default {
  cleanUrls: false
}

Next Steps

Performance Optimization

Learn how to optimize your VitePress site for maximum performance

Custom Domain

Set up a custom domain for your deployed site

Analytics

Add analytics tracking to your VitePress site

SEO

Optimize your site for search engines

Getting Started

Core Concepts

Customization

Advanced

Deploying Your VitePress Site

Deploying Your VitePress Site

Prerequisites

Build and Test Locally

Setting a Public Base Path

HTTP Cache Headers

Understanding Asset Hashing

Recommended Cache Headers

Platform-Specific Guides

Netlify / Vercel / Cloudflare Pages / AWS Amplify / Render

GitHub Pages

GitLab Pages

Azure Static Web Apps

Firebase

Surge

Custom Nginx Server

Additional Platforms

CloudRay

Hostinger

Kinsta

Stormkit

Build Options

Output Directory

Base Path at Build Time

MPA Mode

Troubleshooting

Build Fails on CI

404 on Deployment

Assets Not Loading

Clean URLs Not Working

Next Steps

Performance Optimization

Custom Domain

Analytics

SEO

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Customization

Advanced

Documentation Index

​Deploying Your VitePress Site

​Prerequisites

​Build and Test Locally

​Setting a Public Base Path

​HTTP Cache Headers

​Understanding Asset Hashing

​Recommended Cache Headers

​Platform-Specific Guides

​Netlify / Vercel / Cloudflare Pages / AWS Amplify / Render

​GitHub Pages

​GitLab Pages

​Azure Static Web Apps

​Firebase

​Surge

​Custom Nginx Server

​Additional Platforms

CloudRay

Hostinger

Kinsta

Stormkit

​Build Options

​Output Directory

​Base Path at Build Time

​MPA Mode

​Troubleshooting

​Build Fails on CI

​404 on Deployment

​Assets Not Loading

​Clean URLs Not Working

​Next Steps

Performance Optimization

Custom Domain

Analytics

SEO

Build docs developers (and LLMs) love

Deploying Your VitePress Site

Prerequisites

Build and Test Locally

Setting a Public Base Path

HTTP Cache Headers

Understanding Asset Hashing

Recommended Cache Headers

Platform-Specific Guides

Netlify / Vercel / Cloudflare Pages / AWS Amplify / Render

GitHub Pages

GitLab Pages

Azure Static Web Apps

Firebase

Surge

Custom Nginx Server

Additional Platforms

Build Options

Output Directory

Base Path at Build Time

MPA Mode

Troubleshooting

Build Fails on CI

404 on Deployment

Assets Not Loading

Clean URLs Not Working

Next Steps