Skip to main content

​
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

1

Build your site

Generate static HTML for production:
npm run docs:build
Built files are output to .vitepress/dist.
2

Preview locally

Test the production build before deploying:
npm run docs:preview
The preview server runs at http://localhost:4173.
3

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. For files in the assets/ directory: 
Cache-Control: max-age=31536000,immutable
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

​
Platform-Specific Guides

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

These platforms work similarly - configure via dashboard:
1

Connect repository

Link your Git repository to the platform.
2

Configure build settings

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

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:
1

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
2

Configure Pages source

In repository settings under Pages, set:
  • Source: GitHub Actions
3

Set base path

Update .vitepress/config.js:
export default {
  base: '/repository-name/'
}
4

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:
1

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

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
3

Deploy

Push to the main branch to trigger the pipeline.

​
Azure Static Web Apps

1

Follow Azure documentation

See the official Azure Static Web Apps guide.
2

Configure build settings

Set these values in your configuration:
  • app_location: /
  • output_location: docs/.vitepress/dist
  • app_build_command: npm run docs:build

​
Firebase

1

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

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:
  1. Base path includes trailing slash: base: '/repo/' not '/repo'
  2. Assets are in docs/public/ or imported in components
  3. 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

Build docs developers (and LLMs) love

Get started for freeTalk to us