Skip to content

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

Closed

Description

@debiru

📚 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

Activity

  1. sarah11918 commented on Feb 3, 2025

    @sarah11918
    Member

    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!

  2. added
    help - confirm behaviourWalk through the example/issue and confirm this is a general behaviour, or a correct update to make.
    help wantedIssues looking for someone to run with them!
    improve or update documentationEnhance / update existing documentation (e.g. add example, improve description, update for changes)
    on Feb 3, 2025
  3. casungo commented on May 20, 2025

    @casungo
    Contributor

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

    Test Setup:

    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.)

  4. vrabe commented on May 27, 2025

    @vrabe
    Contributor

    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.

  5. ben-milanko commented on May 27, 2025

    @ben-milanko
    Contributor

    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.

  6. sarah11918 commented on May 28, 2025

    @sarah11918
    Member

    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!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    help - confirm behaviourWalk through the example/issue and confirm this is a general behaviour, or a correct update to make.help wantedIssues looking for someone to run with them!improve or update documentationEnhance / update existing documentation (e.g. add example, improve description, update for changes)

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions