How to Set the Base Path for a Static Site Deployed to a Subdirectory

A site served from /repo/ needs its asset base set to that prefix or every relative link 404s.

Set the framework base option (Vite base, Astro base, Next basePath, Hugo baseURL) to the subdirectory. Inject it at build time so the same repo can deploy to root or a subpath.

Steps

• Determine the URL prefix (for project Pages it is /<repo>/).
• Set the framework base option to that prefix.
• Pass it via an env var so CI controls it.
• Rebuild; asset URLs now include the prefix.

Build config

# vite.config.js reads BASE_PATH from CI
# export default defineConfig({ base: process.env.BASE_PATH || '/' })

- run: BASE_PATH=/my-repo/ npm run build

# equivalents:
#   astro build --base /my-repo
#   next build            # with basePath: '/my-repo' in next.config.js
#   hugo --baseURL https://user.github.io/my-repo/

Gotchas

• A custom domain serves from root, so set the base to / in that case.
• Client-side routers need their own base (React Router basename, Vue Router history base).
• Hard-coded absolute /assets/... links ignore the base and break in a subdirectory.

Related guides