Astro base Path: Fix Broken Assets and Links Under a Subfolder

Separate site from base#

These two settings answer different questions:

For a GitHub Pages project site, the configuration normally looks like this:

1
import { defineConfig } from 'astro/config';
2

3
export default defineConfig({
4
  site: 'https://octocat.github.io',
5
  base: '/my-repo',
6
  trailingSlash: 'always',
7
});

The public URL is now https://octocat.github.io/my-repo/, not https://octocat.github.io/. A user site whose repository is named octocat.github.io is the important exception: it is published at the origin root, so it usually does not need a repository base.

Do not use site as a substitute for base. site helps Astro produce absolute URLs such as canonical and sitemap URLs; it does not tell Astro that every page and asset lives below /my-repo.

Astro’s GitHub Pages deployment guide shows the same distinction. If you later move the site to a custom domain, remove the repository base and update site after verifying every internal link.

Prefix URLs that you own#

Astro can process imported assets, but URLs typed by hand are still your responsibility. The common failures are:

• href="/about/" points to the domain root instead of the project root.
• src="/logo.svg" looks for a file outside the repository subpath.
• fetch("/data/posts.json") sends the request to the wrong origin path.
• A client-side router or third-party widget builds links without knowing the base.

Use BASE_URL at the boundary where your code creates the URL:

1
---
2
const aboutUrl = import.meta.env.BASE_URL + 'about/';
3
const logoUrl = import.meta.env.BASE_URL + 'logo.svg';
4
---
5

6
<a href={aboutUrl}>About</a>
7
<img src={logoUrl} alt="Site logo" />

The value of BASE_URL follows Astro’s trailing-slash configuration. Keep the path fragments in the example relative to that value; do not add another leading slash unless your helper intentionally normalizes it.

For client code, expose the base through the generated bundle rather than assuming that / is the application root:

1
const assetUrl = import.meta.env.BASE_URL + 'data/posts.json';
2
const response = await fetch(assetUrl);

If a library requires a browser-relative URL, document.baseURI can be a useful second check. The key is that the generated request must contain the same public prefix as the page that made it.

Watch the difference between imported and public files#

An image imported from a component is part of Astro’s build pipeline. A file placed in public/ is copied as a static URL, so references such as /favicon.svg or /robots.txt still need a deployment-aware path when they are used inside page markup or client code.

For a public file, verify both sides:

1
---
2
const manifestUrl = import.meta.env.BASE_URL + 'manifest.webmanifest';
3
---
4

5
<link rel="manifest" href={manifestUrl} />

For a component image, prefer the normal Astro asset import and let Astro generate the final file URL. Do not convert every image into a manually assembled string just to add base; that can bypass image processing and create a second path bug.

The same rule applies to Pagefind. A local preview can find dist/pagefind/ even when the deployed HTML points at /pagefind/ instead of /my-repo/pagefind/. Compare the generated URL with the actual published artifact using Pagefind on GitHub Pages: Fix Missing Search Assets After Deploy.

Test the generated site at its real path#

Build first, then inspect the files and HTML:

1
pnpm build
2
find dist -maxdepth 3 -type f | sort
3
rg -n 'href="/|src="/|url\(/' dist
4
rg -n '/my-repo/' dist

The first search is not automatically an error: it can match canonical URLs or intentionally root-relative data. Use it to find candidates, then check whether the URL should include /my-repo/. The second search should show the configured prefix in pages and asset references where it is required.

Test a deployed project page as well:

1
curl -I https://octocat.github.io/my-repo/
2
curl -I https://octocat.github.io/my-repo/about/
3
curl -I https://octocat.github.io/my-repo/logo.svg

If the HTML loads but the stylesheet or image returns 404, inspect the failing request URL in the browser network panel. If every URL has the right prefix but the server still returns 404, the host or deployment artifact is the next boundary. The Astro static route 404 guide covers the separate case where the host cannot map a generated route to its index file.

Avoid two common configuration traps#

FAQ#