Great catch! The code example was updated, but not the text describing the proper use of base.

I would happily accept a PR from someone who carefully goes through a deploy and checks whether in fact the slash is necessary, whether both work, and then makes updates throughout the page to text instructions/explanations as necessary.

In particular, the advice to update all your links href with /my-repo/... is probably still correct (no matter how base is configured, with or without a slash, it should function the same), but I would also make sure to confirm that!

Adding help wanted to this issue, and someone is welcome to investigate further!

Hi everyone,
I've done some testing on this, and here are my findings regarding the base configuration for GitHub Pages deployment:

Test Setup:

• Astro docs starter site
• GitHub Actions deployment as per the current guide
• Repo deployed to https://casungo.github.io/testSlashAstro/
• Source: https://github.com/casungo/testSlashAstro

Configurations Tested:

1. base: "testSlashAstro" (no leading slash)
   • astro.config.mjs:

     export default defineConfig({
       site: "https://casungo.github.io",
       base: "testSlashAstro",
     });

2. base: "/testSlashAstro" (with leading slash)
   • astro.config.mjs:

     export default defineConfig({
       site: "https://casungo.github.io",
       base: "/testSlashAstro",
     });

Results for BOTH configurations were identical:

• Site Accessibility: The site was correctly deployed and accessible at https://casungo.github.io/testSlashAstro/. This means the base path itself was correctly applied regardless of the leading slash.
• Root Page Assets: Assets (e.g., fonts) linked with relative paths on the root page (/testSlashAstro/) loaded correctly from /testSlashAstro/fonts/....
• Nested Page Assets: On nested pages (e.g., /testSlashAstro/blog/), assets referenced with root-relative paths in CSS (e.g., url(/fonts/...) which the browser tries to fetch from https://casungo.github.io/fonts/...) resulted in a 404.
• Root-Relative Links: Astro components using root-relative links (e.g., <HeaderLink href="/about">) resolved to https://casungo.github.io/about (404) instead of the expected https://casungo.github.io/testSlashAstro/about.

So:

1. The presence or absence of a leading slash in the base option does not seem to affect the final deployment subpath. Both configurations deployed to the correct subpath.
2. The most robust way to handle this in Astro is likely by using import.meta.env.BASE_URL for constructing all site-internal links and asset paths.

I'll open a PR shortly with proposed changes to github.mdx to reflect these findings and improve the page.

(Side note: I also encountered an issue where the withastro/action@v3 failed because pnpm version wasn't specified. I fixed it by adding "packageManager": "pnpm@<version>" to package.json. This seems like a separate issue that might need its own bug report/doc update for the action.)

It doesn't completely answer the question. In #7481 @ben-milanko found the leading slash causes links under _astro folder broken. The test site doesn't have links inside _astro. So I can't see the leading slash affects these paths or not from the test.

I can't remember the exact conditions around the original issue I had with the base path, but I have run into the issue with leading underscore files not loading on GitHub pages.

I found this post which explains it is due to GitHub's Jekyll processing. After using their suggested fix everything worked correctly.

It would probably be good to include this in the docs for deployments to GitHub pages.