1
Is your site not working after you’ve deployed to Github Pages?
2
​
3
You see a blank page, or maybe the homepage shows up fine, but then you click on a link and nothing happens. You pop up dev inspector only to find a bunch of 404 status codes.
4
​
5
It happens to many developers — the website works fine on localhost but after deploying to Github Pages, everything breaks.
6
​
7
By understanding the core problem, you will be able to spot it and prevent it from happening in all your future deployments, not just on Github Pages.
8
​
9
Let’s investigate the issue and make your site work as expected in production.
10
​
11

What are root-relative links?

12
​
13
To better understand why links often break when deploying to Github Pages, first we need to learn what root-relative links are.
14
​
15
Root-relative links1 are links that start with a forward slash (/). When clicked, a root-relative link ignores the path location of the current URL. Which part of an URL is the path? Everything that comes after the domain. The path of the following URL, for example, https://example.com/blog/articles is /blog/articles.
16
​
17
A root-relative link always leads to the same path within the current domain, regardless of where it is found. Consider the following examples:
18
​
19

20
<!--
21
  Root-relative links ignore the current URL and always lead
22
  to the same path within the current domain
23
-->
24
​
25
<!-- Current location: https://example.com/ -->
26
<a href="/awesome-post"> <!-- leads to: https://example.com/awesome-post -->
27
​
28
<!-- Current location: https://example.com/blog -->
Is your site not working after you’ve deployed to Github Pages?

You see a blank page, or maybe the homepage shows up fine, but then you click on a link and nothing happens. You pop up dev inspector only to find a bunch of 404 status codes.

It happens to many developers — the website works fine on localhost but after deploying to Github Pages, everything breaks.

By understanding the core problem, you will be able to spot it and prevent it from happening in all your future deployments, not just on Github Pages.

Let’s investigate the issue and make your site work as expected in production.

What are root-relative links?
To better understand why links often break when deploying to Github Pages, first we need to learn what root-relative links are.

Root-relative links1 are links that start with a forward slash (/). When clicked, a root-relative link ignores the path location of the current URL. Which part of an URL is the path? Everything that comes after the domain. The path of the following URL, for example, https://example.com/blog/articles is /blog/articles.

A root-relative link always leads to the same path within the current domain, regardless of where it is found. Consider the following examples:

<!--
	Root-relative links ignore the current URL and always lead
	to the same path within the current domain
-->

<!-- Current location: https://example.com/ -->
<a href="/awesome-post"> <!-- leads to: https://example.com/awesome-post -->

<!-- Current location: https://example.com/blog -->
<a href="/awesome-post"> <!-- leads to: https://example.com/awesome-post -->

<!-- Current location: https://example.com/blog/articles -->
<a href="/awesome-post"> <!-- leads to: https://example.com/awesome-post -->

#blog #github #github pages