You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
(en) github.mdx: The description of the text is discrepancy. #10868
📋 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)
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!
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:
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.
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!
Activity
sarah11918 commentedon Feb 3, 2025
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
hrefwith/my-repo/...is probably still correct (no matter howbaseis configured, with or without a slash, it should function the same), but I would also make sure to confirm that!Adding
help wantedto this issue, and someone is welcome to investigate further!casungo commentedon May 20, 2025
Hi everyone,
I've done some testing on this, and here are my findings regarding the
baseconfiguration for GitHub Pages deployment:Test Setup:
Configurations Tested:
base: "testSlashAstro"(no leading slash)astro.config.mjs:base: "/testSlashAstro"(with leading slash)astro.config.mjs:Results for BOTH configurations were identical:
https://casungo.github.io/testSlashAstro/. This means thebasepath itself was correctly applied regardless of the leading slash./testSlashAstro/) loaded correctly from/testSlashAstro/fonts/..../testSlashAstro/blog/), assets referenced with root-relative paths in CSS (e.g.,url(/fonts/...)which the browser tries to fetch fromhttps://casungo.github.io/fonts/...) resulted in a 404.<HeaderLink href="/about">) resolved tohttps://casungo.github.io/about(404) instead of the expectedhttps://casungo.github.io/testSlashAstro/about.So:
baseoption does not seem to affect the final deployment subpath. Both configurations deployed to the correct subpath.import.meta.env.BASE_URLfor constructing all site-internal links and asset paths.I'll open a PR shortly with proposed changes to
github.mdxto reflect these findings and improve the page.(Side note: I also encountered an issue where the
withastro/action@v3failed becausepnpmversion wasn't specified. I fixed it by adding"packageManager": "pnpm@<version>"topackage.json. This seems like a separate issue that might need its own bug report/doc update for the action.)vrabe commentedon May 27, 2025
It doesn't completely answer the question. In #7481 @ben-milanko found the leading slash causes links under
_astrofolder 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.ben-milanko commentedon May 27, 2025
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.
sarah11918 commentedon May 28, 2025
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!