fix: resolve blank page on GitHub Pages sub-path deployment by Copilot · Pull Request #198 · SillyLittleTech/Portf

Copilot · 2026-03-26T11:10:09Z

Deploying to a sub-path (e.g. /Portf/) produced a blank page because Vite built with base: "/", so every asset reference pointed at the domain root and 404'd silently. The client-side router also broke because window.location.pathname returned the full /Portf/privacy-policy prefix, which matched no routes.

Changes

vite.config.ts — adds base: process.env.VITE_BASE_URL ?? "/". Includes scenario-annotated comments for root domain, GitHub Pages sub-path, and generic CDN deployments so template users know exactly what to set and where.
src/utils/navigation.ts — reads import.meta.env.BASE_URL (Vite-injected) into BASE_PATH at module init. getCurrentPath() strips the prefix before route matching; navigateTo() re-applies it before history.pushState. Both helpers are no-ops when BASE_PATH is empty (root deployment). Includes a clear comment block telling template users they never need to touch this file.
package.json — build:pages now runs tsc -b && VITE_BASE_URL=/Portf/ vite build (env var scoped to vite build only). Adds a build:pages:help script that echoes template guidance at the terminal.
.github/workflows/github-pages.yml — exposes VITE_BASE_URL as an explicit env: block on the Build step with an inline change instruction. Adds a header comment block listing the two values a fork must update (VITE_BASE_URL here + in package.json).

// vite.config.ts
base: process.env.VITE_BASE_URL ?? "/",
// build:pages sets VITE_BASE_URL=/Portf/  →  assets emit as /Portf/assets/…
// omit VITE_BASE_URL for root-domain deploys  →  no change needed

Original prompt

This section details on the original issue you should resolve

<issue_title>Task: Update Project to be ready for pages template presentation</issue_title>
<issue_description>Get code ready to be able to be published to GH pages, in order to be shown as a presented template. </issue_description>

<agent_instructions>Thought to be completed in #197 on loading GH page, displays blank page @ https://projects.sillylittle.tech/Portf/
Discover error and please resolve/fix. In fixing PR, please add "fixes #194"</agent_instructions>

Comments on the Issue (you are @copilot in this section)

Fixes Task: Update Project to be ready for pages template presentation #194

📱 Kick off Copilot coding agent tasks wherever you are with GitHub Mobile, available on iOS and Android.

Co-authored-by: kiyarose <75678535+kiyarose@users.noreply.github.com> Agent-Logs-Url: https://github.com/SillyLittleTech/Portf/sessions/2cadf2ca-1550-42e3-8991-ae0c7fbc628e

Copilot

Pull request overview

Fixes blank-page deployments when the app is served from a GitHub Pages repo sub-path by ensuring both Vite asset URLs and the client-side router respect the configured base path.

Changes:

Configure Vite base via VITE_BASE_URL to emit correct asset URLs for sub-path deployments.
Add base-path stripping/applying in navigation helpers using import.meta.env.BASE_URL.
Update Pages build scripts and workflow to provide VITE_BASE_URL during GitHub Pages builds.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

File	Description
`vite.config.ts`	Adds `base` driven by `VITE_BASE_URL` with explanatory deployment scenarios.
`src/utils/navigation.ts`	Strips base path from `window.location.pathname` for route matching and re-applies it on navigation.
`package.json`	Adds a `build:pages` script variant that builds with a sub-path base and a help script.
`.github/workflows/github-pages.yml`	Sets `VITE_BASE_URL` for the Pages build step and documents template-user edits.

Copilot · 2026-03-26T11:26:22Z

package.json

+    "build:pages": "tsc -b && VITE_BASE_URL=/Portf/ vite build",
+    "build:pages:help": "echo \"\\nTEMPLATE USERS: build:pages sets VITE_BASE_URL=/Portf/ for the showcase sub-path.\\nIf your repo has a different name, replace /Portf/ with /<your-repo-name>/ in this script\\nand in the VITE_BASE_URL env var in .github/workflows/github-pages.yml.\\nDeploying to a root domain? Use 'npm run build' instead (no sub-path needed).\\n\"",


build:pages sets an env var using POSIX-style VITE_BASE_URL=/Portf/ ..., which won’t work on Windows shells. Consider switching to a cross-platform approach (e.g., a CLI --base flag or cross-env) so template users can run the script locally on any OS.

Suggested change

"build:pages": "tsc -b && VITE_BASE_URL=/Portf/ vite build",

"build:pages:help": "echo \"\\nTEMPLATE USERS: build:pages sets VITE_BASE_URL=/Portf/ for the showcase sub-path.\\nIf your repo has a different name, replace /Portf/ with /<your-repo-name>/ in this script\\nand in the VITE_BASE_URL env var in .github/workflows/github-pages.yml.\\nDeploying to a root domain? Use 'npm run build' instead (no sub-path needed).\\n\"",

"build:pages": "tsc -b && vite build --base=/Portf/",

"build:pages:help": "echo \"\\nTEMPLATE USERS: build:pages runs 'vite build --base=/Portf/' for the showcase sub-path.\\nIf your repo has a different name, replace /Portf/ with /<your-repo-name>/ in this script\\nand in the VITE_BASE_URL env var in .github/workflows/github-pages.yml.\\nDeploying to a root domain? Use 'npm run build' instead (no sub-path needed).\\n\"",

Copilot · 2026-03-26T11:26:22Z

.github/workflows/github-pages.yml

+        # TEMPLATE USERS: change /Portf/ below to /<your-repo-name>/ — or
+        # remove the env block entirely when deploying to a root domain.
+        env:
+          VITE_BASE_URL: /Portf/
        run: npm run build:pages


The workflow sets VITE_BASE_URL in the Build step, but npm run build:pages also hard-codes VITE_BASE_URL=/Portf/ in package.json; the script-level assignment will override whatever is set here. To avoid drift/confusion for template users, pick a single source of truth (either remove the env block here and rely on the script, or remove the hard-coded value from the script and rely on this env).

Copilot · 2026-03-26T11:26:22Z

.github/workflows/github-pages.yml

+# If you are using this as a template for your own project you will need to
+# update TWO values so that assets load from the correct path:
+#
+#   1. VITE_BASE_URL (in the Build step below)
+#      Set this to "/<your-repo-name>/" — include both slashes.
+#      Example: if your repo is "github.com/jane/my-portfolio", use "/my-portfolio/".
+#      If you are deploying to a root domain (e.g. https://jane.github.io) or a
+#      custom domain pointed at the repo root, set VITE_BASE_URL to "/" or
+#      remove the env block entirely.
+#
+#   2. The "base" value in vite.config.ts
+#      Normally this is driven automatically by VITE_BASE_URL above, so you
+#      only need to change it if you want to hard-code the path instead of
+#      using the environment variable.


The header comment says template users must update TWO values, including “the base value in vite.config.ts”, but the config now reads base from VITE_BASE_URL and typically doesn’t need editing. Rewording this section to point to the actual second source (the build:pages script) or to clarify that vite.config.ts usually stays unchanged would prevent misconfiguration.

Initial plan

15e109e

Copilot AI assigned Copilot and kiyarose Mar 26, 2026

Copilot started work on behalf of kiyarose March 26, 2026 11:10 View session

kiyarose added the bug Something isn't working label Mar 26, 2026

fix: resolve blank page on GitHub Pages sub-path deployment (fixes #194)

0d075e8

Co-authored-by: kiyarose <75678535+kiyarose@users.noreply.github.com> Agent-Logs-Url: https://github.com/SillyLittleTech/Portf/sessions/2cadf2ca-1550-42e3-8991-ae0c7fbc628e

Copilot AI changed the title ~~[WIP] Fix blank page issue on GH pages for template presentation~~ fix: resolve blank page on GitHub Pages sub-path deployment Mar 26, 2026

Copilot AI requested a review from kiyarose March 26, 2026 11:19

Copilot finished work on behalf of kiyarose March 26, 2026 11:19

kiyarose marked this pull request as ready for review March 26, 2026 11:22

Copilot AI review requested due to automatic review settings March 26, 2026 11:22

Copilot started reviewing on behalf of kiyarose March 26, 2026 11:22 View session

kiyarose merged commit 6d1065b into main Mar 26, 2026
24 checks passed

kiyarose deleted the copilot/fix-blank-page-on-gh-pages branch March 26, 2026 11:26

Copilot AI reviewed Mar 26, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix: resolve blank page on GitHub Pages sub-path deployment#198

fix: resolve blank page on GitHub Pages sub-path deployment#198
kiyarose merged 2 commits intomainfrom
copilot/fix-blank-page-on-gh-pages

Copilot AI commented Mar 26, 2026 •

edited

Loading

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Mar 26, 2026

Uh oh!

Copilot AI Mar 26, 2026

Uh oh!

Copilot AI Mar 26, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		"build:pages": "tsc -b && VITE_BASE_URL=/Portf/ vite build",
		"build:pages:help": "echo \"\\nTEMPLATE USERS: build:pages sets VITE_BASE_URL=/Portf/ for the showcase sub-path.\\nIf your repo has a different name, replace /Portf/ with /<your-repo-name>/ in this script\\nand in the VITE_BASE_URL env var in .github/workflows/github-pages.yml.\\nDeploying to a root domain? Use 'npm run build' instead (no sub-path needed).\\n\"",

Conversation

Copilot AI commented Mar 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Comments on the Issue (you are @copilot in this section)

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Copilot AI commented Mar 26, 2026 •

edited

Loading