GitHub Pages: configure base path for project site without changing asset URLs #188844

bsastregx · 2026-03-07T01:19:38Z

bsastregx
Mar 7, 2026

Select Topic Area

Question

Body

I'm hosting a project site on GitHub Pages under a subpath (e.g., /june/). My HTML, CSS, and JS use absolute URLs starting with /, and I want them to resolve correctly without modifying the repository files. Is there a way to configure GitHub Pages so the base path points to the project folder, making absolute URLs work automatically?

https://bsastregx.github.io/june/#spacing

Many thanks in advance

SIMARSINGHRAYAT · 2026-03-07T04:27:01Z

SIMARSINGHRAYAT
Mar 7, 2026

Great question! This is a common challenge with GitHub Pages and relative asset paths. Here's how to handle this properly:

Solution 1: Use the {% raw %} tag in Jekyll

If you're using Jekyll (GitHub Pages default), add this to your HTML <head>:

<base href="{{ site.baseurl }}/">

This automatically adjusts all relative URLs based on your base path configuration.

Solution 2: Update Your Jekyll Configuration

In _config.yml:

baseurl: "/june" # Your subpath
url: "https://basregx.github.io" # Your site URL

Then reference assets with the baseurl filter:

<link rel="stylesheet" href="{{ '/css/style.css' | relative_url }}">
<img src="{{ 'images/logo.png' | relative_url }}" alt="Logo">

Solution 3: For Non-Jekyll Sites (HTML/CSS/JS)

Add a base path variable at the top of your HTML:

<script>
  window.basePath = '/june';
</script>

In your CSS, make assets relative:

<!-- Instead of: -->
<link rel="stylesheet" href="/css/style.css">

<!-- Use: -->
<link rel="stylesheet" href="css/style.css">  <!-- relative path -->

In JavaScript, prepend basePath:

const imageUrl = window.basePath + '/images/photo.jpg';

Solution 4: Using the <base> HTML Tag

The simplest approach - add this in your <head> tag:

<base href="/june/">

This makes ALL relative paths resolve from /june/ automatically.

Recommended Approach for Your Situtation:

Since you're using absolute URLs starting with /, I'd recommend:

Change absolute paths to relative paths in your CSS/HTML
Add the <base> tag with your subpath
Test locally with: bundle exec jekyll serve --baseurl /june

Testing:

Before deploying:

# Test with baseurl
bundle exec jekyll serve --baseurl /june

# Visit: http://localhost:4000/june/

Troubleshooting:

Check browser DevTools Network tab to see actual asset URLs being requested
Ensure your repo is named correctly (for user.github.io/repo sites)
Double-check GitHub Pages settings - make sure you're publishing from the correct branch

Let me know if you need help with any specific asset type (CSS, images, JavaScript)!

0 replies

Sandeshkadel · 2026-03-07T04:29:54Z

Sandeshkadel
Mar 7, 2026

1. Problem Description

When hosting a project site using GitHub Pages, the site is not served from the root of the domain. Instead, it is served under a repository subpath.

Example project site:

https://bsastregx.github.io/june/

In this configuration, the effective base path of the website becomes:

/june/

However, many projects are written using root-absolute asset URLs such as:

These paths begin with /, which instructs the browser to resolve them relative to the domain root.

Therefore the browser attempts to load:

https://bsastregx.github.io/css/style.css
https://bsastregx.github.io/js/app.js
https://bsastregx.github.io/images/logo.png

But the real files are located at:

https://bsastregx.github.io/june/css/style.css
https://bsastregx.github.io/june/js/app.js
https://bsastregx.github.io/june/images/logo.png

Because of this mismatch, CSS, JavaScript, and image assets return 404 errors and the website may appear unstyled or partially broken.

This behavior is common for GitHub Pages project sites.

The example page where the issue can be observed is:

https://bsastregx.github.io/june/#spacing

# 2. Root Cause Analysis

GitHub Pages supports two types of websites:

User / Organization Site

Format:

https://username.github.io/

Example:

https://bsastregx.github.io/

In this case the website is hosted at the domain root.

Absolute URLs such as /css/style.css work correctly.

### Project Site

Format:

https://username.github.io/repository-name/

Example:

https://bsastregx.github.io/june/

Here the repository name (june) becomes part of the URL path.

Because of this, the actual base path becomes /june/.

However, browsers do not automatically prepend this path when resolving root URLs.

Therefore /css/style.css still points to the domain root instead of /june/css/style.css.

GitHub Pages does not automatically rewrite these URLs because it is a static hosting system and does not perform runtime HTML rewriting or request proxying.

# 3. Why GitHub Pages Cannot Automatically Fix It

GitHub Pages intentionally behaves as a simple static server. It does not:

• rewrite absolute paths in HTML
• modify asset URLs dynamically
• inject repository paths into links
• perform server-side routing for static files

Therefore any asset URL that begins with / will always resolve to:

https://username.github.io/

instead of

https://username.github.io/repository/

# 4. Correct Solution (Recommended)

The most effective solution that preserves all existing asset URLs is to define a base path using the HTML <base> element.

The <base> tag tells the browser what base URL should be used when resolving relative and root-based links inside the document.

This allows existing asset URLs to work without rewriting every path in the repository.

# 5. Implementation Steps

Step 1 — Open the Main HTML File

Open the primary entry file of the site.

Typically:

index.html

### Step 2 — Add a Base Path Declaration

Inside the <head> section of the document, insert the following line:

Example full head section:

<title>Project Site</title> <script src="/js/app.js"></script>

### Step 3 — Commit the Change

Save the file and commit the change to the repository.

Example workflow:

git add index.html
git commit -m "Add base path for GitHub Pages project site"
git push

Step 4 — Wait for GitHub Pages Deployment

GitHub Pages will rebuild the site automatically after the push.

Deployment normally takes between 30 seconds and 2 minutes.

# 6. How the Fix Works

Before the fix:

/css/style.css

is interpreted as:

https://bsastregx.github.io/css/style.css

After adding the base tag:

the browser resolves the same path as:

https://bsastregx.github.io/june/css/style.css

No changes are required to the existing asset references.

All CSS, JavaScript, images, and internal links will now resolve correctly relative to the project folder.

# 7. Verification Procedure

To verify that the fix is working correctly:

Open the site in a browser.
Open the browser Developer Tools.
Navigate to the Network tab.
Refresh the page.

Confirm that asset requests load from paths such as:

/june/css/style.css
/june/js/app.js
/june/images/logo.png

All requests should return HTTP status 200 instead of 404.

# 8. Alternative Solutions

If modifying HTML is not possible, the following alternatives may also be used.

Option A — Convert Asset URLs to Relative Paths

Example change:

From:

/css/style.css

To:

css/style.css

### Option B — Use a Static Site Generator Configuration

If the project uses Jekyll, configure _config.yml:

url: https://bsastregx.github.io/
baseurl: /june

Then reference assets using:

{{ site.baseurl }}/css/style.css

### Option C — Use a Custom Domain

If the site is configured with a custom domain such as:

https://example.com/

then the repository is served at the root path and absolute URLs will work automatically.

# 9. Recommended Approach

For the specific scenario described, the most practical and minimal change is:

Add the following tag to the <head> section of the main HTML file:

This approach:

• requires only a single modification
• keeps existing asset URLs unchanged
• works for CSS, JavaScript, images, and internal links
• is fully compatible with GitHub Pages hosting

# 10. Final Result

After implementing the base path configuration, the site:

https://bsastregx.github.io/june/#spacing

will load all assets correctly and function as intended without requiring repository-wide path modifications.

0 replies

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

GitHub Community

GitHub Pages: configure base path for project site without changing asset URLs #188844

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Replies: 2 comments

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Select a reply

Uh oh!

GitHub Community

GitHub Pages: configure base path for project site without changing asset URLs #188844

Uh oh!

Uh oh!

bsastregx Mar 7, 2026

Select Topic Area

Body

Replies: 2 comments

Uh oh!

SIMARSINGHRAYAT Mar 7, 2026

Uh oh!

Sandeshkadel Mar 7, 2026

User / Organization Site

Step 1 — Open the Main HTML File

Step 4 — Wait for GitHub Pages Deployment

Option A — Convert Asset URLs to Relative Paths

bsastregx
Mar 7, 2026

SIMARSINGHRAYAT
Mar 7, 2026

Sandeshkadel
Mar 7, 2026