Fixing Broken Relative Links on GitHub Pages
What do you do when your website's relative links work on your local machine but not when deployed on GitHub Pages? This guide will walk through solutions.
Sep 15, 2020 • 4 Minute Read
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.
<link href="/static/css/styles.css" rel="stylesheet">
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.
{
output: {
publicPath: argv.mode === 'production' ? '/my-static-website' : '/',
}
}
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:
{
"homepage": "https://company.github.io/my-static-website"
}
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.
