(en) `github.mdx`: The description of the text is discrepancy.

📚 Subject area/topic

guides/deploy

📋 Page(s) affected (or suggested, for new content)

https://docs.astro.build/en/guides/deploy/github/

📋 Description of content that is out-of-date or incorrect

The leading slash in the value of the base parameter is being removed by #7481.

However, the text explains that the base parameter value must be prefixed with slash.

The value for base should be your repository’s name starting with a forward slash, for example /my-blog. This is so that Astro understands your website’s root is /my-repo, rather than the default /.

Incidentally, when I tried deploying with GitHub Pages, I was able to deploy successfully with or without the slash. What exactly was the problem with #7481? And please think of a way to resolve this discrepancy.

NOTE: Or rather, there are several inaccurate statements in addition to the points pointed out above. You may want to carefully verify that the entire text is correct.

🖥️ Reproduction in StackBlitz (if reporting incorrect content or code samples)

No response

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.

Thank you for this, @ben-milanko ! I had to double check docs because I was sure we had something about .nojekyll (yes, that's a known thing that GitHub Pages was originally built specifically for Jekyll sites, and so if you don't have one, you have to tell it!)

I wonder whether some update to this page removed mention of it at some point, because I KNOW that is a part of the underlying pain of deploying there!