Fix VitePress Routing Errors on GitHub Pages (Base Path + 404)

Tested on: VitePress 1.6.3, GitHub Pages project site user.github.io/my-docs/ Symptoms: CSS 404, client navigation to 404, refresh on nested route fails.

TL;DR

• Set base: '/your-repo/' in VitePress config.
• Use relative asset paths; verify assetsDir.
• Add 404.html SPA fallback for direct URL access.

Set base path

.vitepress/config.mts:

export default defineConfig({
  base: '/my-docs/',
  cleanUrls: true
})

Critical: trailing slash in base.

Build output

npm run docs:build
# output: docs/.vitepress/dist (or .vitepress/dist if docs at root)

GitHub Actions deploy docs/.vitepress/dist to gh-pages branch root OR use Actions Pages artifact.

404 fallback for direct URL refresh

GitHub Pages doesn't auto-rewrite /guide/install to SPA.

docs/public/404.html — copy index.html after build script:

package.json:

"docs:build": "vitepress build docs && cp docs/.vitepress/dist/index.html docs/.vitepress/dist/404.html"

Or use spa fallback only for project sites — user sites at root may not need it with cleanUrls + proper file structure.

Actually VitePress static build emits guide/install/index.html — refresh works if cleanUrls matches server.

GitHub Pages serves index.html inside directories — works for /my-docs/guide/install/.

Breakage was missing base on assets:

GET /assets/chunk.js 404

Should be /my-docs/assets/chunk.js.

Workflow

.github/workflows/docs.yml:

- run: npm run docs:build
- uses: actions/upload-pages-artifact@v3
  with:
    path: docs/.vitepress/dist

Errors

Blank page, console: Failed to fetch module

base was /my-docs without trailing slash — Vite generated wrong asset URLs.

Router base mismatch

Mixed base in config and hardcoded /guide/ links. Use relative markdown links.

Verify

npm run docs:preview -- --base /my-docs/
curl -I http://localhost:4173/my-docs/guide/getting-started/

Production:

curl -I https://user.github.io/my-docs/assets/
# 403/404 ok for directory; chunk URL must 200

Result

All nested routes + refresh work. Asset 404s eliminated.

FAQ

Why do VitePress internal links 404 on GitHub Pages?

Missing or wrong base config. VitePress generates absolute paths from base — mismatch breaks all sub-routes.

Should I use cleanUrls on GitHub Pages with VitePress?

GitHub Pages doesn't natively support clean URLs for SPAs. Prefer trailing slash config matching your host setup.

Can I use a custom domain with VitePress on GitHub Pages?

Yes — set base to '/' when using a custom domain on a user/org site, or keep /repo/ for project pages.