Clarify GitHub Pages base config and withastro/action usage

src/content/docs/en/guides/deploy/github.mdx

@@ -18,68 +18,99 @@ Astro maintains the official `withastro/action` to deploy your project with very
 
 ## Configure Astro for GitHub Pages
 
-### Deploying to a `github.io` URL 
+### Deploying to a `github.io` URL
 
-Set the [`site`](/en/reference/configuration-reference/#site) and [`base`](/en/reference/configuration-reference/#base) options in `astro.config.mjs`.
+When deploying to a URL that includes your repository name as a subpath (like `https://username.github.io/astronaut/`), you'll need to set both the [`site`](/en/reference/configuration-reference/#site) and [`base`](/en/reference/configuration-reference/#base) options in `astro.config.mjs`.
 
 ```js title="astro.config.mjs" ins={4-5}
 import { defineConfig } from 'astro/config'
 
 export default defineConfig({
-  site: 'https://astronaut.github.io',
-  base: 'my-repo',
+  site: 'https://username.github.io', // Replace with your GitHub Pages URL
+  base: 'astronaut', // Replace with your repository name
 })
 ```
 
 #### `site`
 
-The value for `site` must be one of the following:
+The value for `site` should be your full GitHub Pages URL. It must be one of the following:
 
-- The following URL based on your username: `https://<username>.github.io`
+- The URL based on your username and repository: `https://username.github.io`
 - The random URL autogenerated for a [GitHub Organization's private page](https://docs.github.com/en/enterprise-cloud@latest/pages/getting-started-with-github-pages/changing-the-visibility-of-your-github-pages-site): `https://<random-string>.pages.github.io/`
 
 #### `base`
 
-A value for `base` may be required so that Astro will treat your repository name (e.g. `/my-repo`) as the root of your website.
-
 :::note
   Don't set a `base` parameter if:
 
-- Your page is served from the root folder.
-- Your repository is located at `https://github.com/<USERNAME>/<USERNAME>.github.io`.
+- Your page is being served from a custom domain.
+- Your repository is named `username.github.io` and you are deploying to `https://username.github.io/`. In this case, your site is already at the root.
 :::
 
-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 `/`.
+The `base` option specifies the subpath where your site will be served.
+- Set `base` to your repository's name, for example `'astronaut'`. Astro will use this to understand that your site's root is `/<your-repo-name>/` rather than the default `/`.
+- A leading slash (e.g., `'/astronaut'`) is also permissible and will typically result in the same behavior, but the common convention and example show it without.
+
+:::caution[Important: Update Links and Asset Paths!]
+When a `base` path is configured (e.g., `'astronaut'`), Astro does **not** automatically prepend this base to your root-relative links or asset paths in your `.astro` files, Markdown, or other content. You **must** update them.
 
-:::caution
-    When this value is configured, all of your internal page links must be prefixed with your `base` value:
+The most reliable way to do this is by using `import.meta.env.BASE_URL`. This environment variable will correctly include your `base` path (e.g., `'/astronaut'`) or be `'/'` if no `base` is set.
 
-```astro ins="/my-repo"
-<a href="/my-repo/about">About</a>
+**Example for links:**
+```astro title="src/components/Header.astro"
+---
+// import.meta.env.BASE_URL will be '/astronaut' if base: 'astronaut'
+// or '/' if no base is set.
+const blogUrl = `${import.meta.env.BASE_URL}/blog/`;
+---
+<nav>
+  <a href={import.meta.env.BASE_URL}>Home</a>
+  <a href={`${import.meta.env.BASE_URL}/about/`}>About</a>
+  <a href={blogUrl}>Blog</a>
+</nav>
 ```
 
-See more about [configuring a `base` value](/en/reference/configuration-reference/#base)
+**Example for images or other static assets:**
+```astro title="src/pages/index.astro"
+---
+// For an image in public/images/hero.png
+const imageUrl = `${import.meta.env.BASE_URL}/images/hero.png`;
+---
+<img src={imageUrl} alt="Hero image" />
+
+<!-- Or directly: -->
+<img src={`${import.meta.env.BASE_URL}/images/another-image.jpg`} alt="Another image" />
+```
+
+For assets referenced in CSS files (e.g., `background-image: url(...)`), you may need to use relative paths from the CSS file to the asset, or ensure your build process correctly handles these paths if they are root-relative. Root-relative paths like `url(/fonts/...)` will resolve from the domain root, not your `base` path.
+
+See more about [configuring a `base` value](/en/reference/configuration-reference/#base) and [`import.meta.env.BASE_URL`](/en/guides/environment-variables/#default-environment-variables).
 :::
 
 ### Using GitHub pages with a custom domain
 
+If you are using a [custom domain](https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site) (e.g., `www.example.com`) with GitHub Pages, your site is served from the root of that domain.
+
 :::tip[Set up a custom domain]
-You can set up a custom domain by adding the following `./public/CNAME` file to your project: 
+You can set up a custom domain by adding a `CNAME` file to your project's `public/` directory:
 
-```js title="public/CNAME"
+``` txt title="public/CNAME"
 sub.mydomain.com
 ```
 
-This will deploy your site at your custom domain instead of `user.github.io`. Don't forget to also [configure DNS for your domain provider](https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site/managing-a-custom-domain-for-your-github-pages-site#configuring-a-subdomain).   
+This will deploy your site at your custom domain instead of `username.github.io`. Don't forget to also [configure DNS for your domain provider](https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site/managing-a-custom-domain-for-your-github-pages-site#configuring-a-subdomain).
 :::
 
-To configure Astro for using GitHub pages with a custom domain, set your domain as the value for `site`. Do not set a value for `base`:
+To configure Astro for using GitHub pages with a custom domain:
+1. Set your custom domain as the value for `site` in `astro.config.mjs`.
+2. **Do not** set a value for `base`, as your site is at the root.
 
 ```js title="astro.config.mjs" ins={4}
 import { defineConfig } from 'astro/config'
 
 export default defineConfig({
-  site: 'https://example.com',
+  site: 'https://www.example.com', // Your custom domain
+  // No 'base' needed when deploying to the root of a custom domain
 })
 ```
 
@@ -88,7 +119,7 @@ export default defineConfig({
 <Steps>
 1. Create a new file in your project at `.github/workflows/deploy.yml` and paste in the YAML below.
 
-    ```yaml title="deploy.yml"
+    ```yaml title=".github/workflows/deploy.yml"
     name: Deploy to GitHub Pages
 
     on:
@@ -115,7 +146,7 @@ export default defineConfig({
             uses: withastro/action@v3
             # with:
               # path: . # The root location of your Astro project inside the repository. (optional)
-              # node-version: 20 # The specific version of Node that should be used to build your site. Defaults to 20. (optional)
+              # node-version: 22 # The specific version of Node that should be used to build your site. Defaults to 22. (optional)
               # package-manager: pnpm@latest # The Node package manager that should be used to install dependencies and build your site. Automatically detected based on your lockfile. (optional)
 
       deploy:
@@ -131,21 +162,21 @@ export default defineConfig({
     ```
 
     :::note
-    The astro action takes a few optional inputs. These can be provided by uncommenting the `with:` line and the input you want to use.
+    The action takes a few optional inputs. These can be provided by uncommenting the `with:` line and the input you want to use. Check the [action's README](https://github.com/withastro/action) for the latest options and versions.
     :::
 
     :::caution
-    The official Astro [action](https://github.com/withastro/action) scans for a lockfile to detect your preferred package manager (`npm`, `yarn`, `pnpm`, or `bun`). You should commit your package manager's automatically generated `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, or `bun.lockb` file to your repository.
+    The official Astro [action](https://github.com/withastro/action) scans for a lockfile (e.g., `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, `bun.lockb`) to detect your preferred package manager. You **must** commit this lockfile to your repository. If you encounter issues with package manager detection (e.g., for `pnpm`), ensure your `package.json` specifies the `packageManager` field (e.g., `"packageManager": "pnpm@8.15.0"`) or set it in the action's `with` block.
     :::
 
-2. On GitHub, go to your repository’s **Settings** tab and find the **Pages** section of the settings.
+2. On GitHub, go to your repository’s **Settings** tab and, under "Code and automation", find the **Pages** section.
 
-3. Choose **GitHub Actions** as the **Source** of your site.  
+3. Choose **GitHub Actions** as the **Source** for your site deployment.
 
-4. Commit the new workflow file and push it to GitHub.  
+4. Commit the new workflow file (`deploy.yml`) and push it to your `main` branch (or your designated deployment branch).
 </Steps>
 
-Your site should now be published! When you push changes to your Astro project’s repository, the GitHub Action will automatically deploy them for you.
+Your site should now be published! When you push changes to your Astro project’s repository, the GitHub Action will automatically build and deploy them for you. You can monitor the progress in the "Actions" tab of your GitHub repository.
 
 ## Examples