Important Update
The Guide Feature will be discontinued after December 15th, 2023. Until then, you can continue to access and refer to the existing guides.
Author avatar

Benney Au

Fixing Broken Relative Links on GitHub Pages

Benney Au

  • Sep 15, 2020
  • 4 Min read
  • 13,704 Views
  • Sep 15, 2020
  • 4 Min read
  • 13,704 Views
Web Development
Client-side Frameworks
React
Front End Web Development

Introduction

GitHub Pages offers a convenient way to host static web content. However, sometimes you may have the frustrating experience of your website's relative links working on your local machine, but not when deployed on GitHub Pages!

This guide will walk you through options for solving this issue. We will look at solutions for websites packaged with Webpack and React Scripts throughout this guide. A basic understanding of how to deploy to static content to GitHub Pages is assumed knowledge for this guide.

Understanding Why Relative Links Are Broken

When you deploy to GitHub Pages, the base URL of your website has the following structure: https://{org}.github.io/{repo}. A subdomain is created for your GitHub organization and your repository's name is appended as a fixed path. This means if your GitHub organization name is "company" and your repository name is "my-static-website", then your website will be hosted at https://company.github.io/my-static-website.

In contrast, when you are developing locally, you are likely serving from localhost:3000 without a path parameter. If you want to include a CSS file for use in your website hosted at localhost:3000/static/css/styles.css, then you will need the following HTML snippet.

1<link href="/static/css/styles.css" rel="stylesheet">
html

Since the href attribute begins with a /, it is an absolute path. This means that your browser looks for the resource by prepending the domain name. Your browser will:

  • Look for the resource at localhost:3000/static/css/styles.css when you test locally
  • Look for the resource at company.github.io/static/css/styles.css when you test on GitHub Pages. This is the incorrect resource location. As mentioned above, your resource is hosted at company.github.io/my-static-website/static/css/styles.css.

The my-static-website path segment is missing. In the following sections, we will look at how to configure your tools to generate the links correctly.

Configuring Webpack

If your website uses Webpack directly to bundle static resources, you typically won't be creating <link /> and <script /> tags manually. Webpack offers the Public Path Configuration Option to control the base path. In our case, we want a base path of my-static-website when it is deployed to GitHub Pages, and none when deployed on GitHub Pages.

Update your webpack.config.js with the following publicPath.

1{
2  output: {
3    publicPath: argv.mode === 'production' ? '/my-static-website' : '/',
4  }
5}
javascript

When you build in production mode, the correct paths should be generated. How to build and deploy a Webpack project is beyond the scope of this guide, however, you can see a full example of this in action in my d3-chart-samples repository.

Configuring React Scripts

If you are using React Scripts, you will not have direct access to the webpack.config.js file. This means that you need to edit the configuration some other way. Luckily, it is just as easy.

Change the homepage property of your package.json file to your base address.

It should look like:

1{
2  "homepage": "https://company.github.io/my-static-website"
3}

When the solution is built, the path segment my-static-website will be present. You can find a full example of a React app deployed to GitHub Pages at Yoga9's SnapShot repository. This repository uses React Scripts and the configuration described above to fix broken relative links.

Conclusion

You have learned why you may have broken links after deploying to GitHub Pages, and we looked at solutions for react-scripts and webpack. If you use a different bundling tool, there is likely a very similar configuration to fix the issue of broken relative links.