How to Deploy VitePress Documentation Sites

VitePress is a Vite-powered static site generator built specifically for documentation. It's what powers the Vue, Vite, and many other project docs — fast builds, instant client-side navigation, built-in search, and clean Markdown authoring. Here's how to deploy a VitePress docs site to production.

How VitePress builds

VitePress takes your Markdown files plus a theme config and produces a static site. By convention your docs live in a docs/ directory with config in docs/.vitepress/config.ts. Build with:

npm run docs:build

This is usually wired in package.json to vitepress build docs, and it outputs to docs/.vitepress/dist. That output directory is the single most important thing to get right when configuring your host — it's nested, not the project root.

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

The base path gotcha

If your docs are served from a subpath (like example.com/docs/), you must set the base option, or every asset and link will 404:

// docs/.vitepress/config.ts
import { defineConfig } from 'vitepress';

export default defineConfig({
  title: 'My Docs',
  description: 'Project documentation',
  base: '/', // use '/docs/' if served from a subpath
});

Serving from the root of your own domain? Keep base: '/'. This is the classic "styles missing on deploy" cause for VitePress and Vite-based sites generally.

Adding search

VitePress includes a built-in local search that requires no external service — just enable it in config:

export default defineConfig({
  themeConfig: {
    search: {
      provider: 'local',
    },
  },
});

Local search indexes your content at build time and runs entirely in the browser — no API keys, no cost. For very large docs you can switch to an Algolia provider later, but local search covers most projects.

Clean URLs and SEO

Set your production URL so generated metadata is correct, and consider enabling clean URLs:

export default defineConfig({
  cleanUrls: true,
  sitemap: {
    hostname: 'https://example.com',
  },
});

cleanUrls drops the .html extension; just confirm your host serves page for page.html, which static hosts generally do.

Deploying on PandaStack (free)

VitePress output is pure static files, perfect for free edge hosting:

1. 1Connect your Git repository as a static site.
2. 2PandaStack auto-detects the framework and runs npm run docs:build.
3. 3Set the output directory to docs/.vitepress/dist (the nested path).
4. 4Add your custom domain — automatic SSL is issued.
5. 5Push — it rebuilds and redeploys with live build logs.

Builds run in fast microVMs. The free tier includes 5 static sites with 100 GB/month bandwidth (Pro and above are unlimited static) — plenty for documentation.

Common pitfalls

• Wrong output directory — it's the nested docs/.vitepress/dist, not dist.
• Missing base — broken assets when served from a subpath.
• Forgetting sitemap.hostname — incomplete SEO metadata.
• Heavy unindexed search needs — start with local search; only add Algolia if you truly outgrow it.

References

• VitePress deployment guide: https://vitepress.dev/guide/deploy
• VitePress getting started: https://vitepress.dev/guide/getting-started
• VitePress site config (base): https://vitepress.dev/reference/site-config
• VitePress search: https://vitepress.dev/reference/default-theme-search
• Vite static deploy notes: https://vite.dev/guide/static-deploy

---

VitePress docs are tiny, fast, and free to host on PandaStack's edge — connect your repo, point the output at docs/.vitepress/dist, and get automatic SSL. Deploy at https://dashboard.pandastack.io