The Elusive Custom GitHub 404 Page

So you want a custom 404 page for your project page, or just any subdirectory? Well, according the GitHub help page, “you must use a custom domain.”

It’s a much desired thing. Google “github custom 404” and you’ll very likely come accross this discussion. Everyone says you can’t.

But I beg to differ. In fact, I did it. All you need is a simple redirect JavaScript on your normal 404 page.

Here’s how I did it:

1. Create your normal 404 per the GitHub guide.
2. Create your custom 404 page wherever you want it to be. I have one in my tags/ subfolder.
3. Add the following script to your normal 404 page:

var url = window.location.href;

var isTagSubdirectory = url.search("https://www.joehxblog.com/tags");

if (isTagSubdirectory > -1) {
  window.location.replace("https://www.joehxblog.com/tags/404.html");
}

Obviously, chang the URLs to match where you want it to go. And you could use if...else if...else if etc. to have multiple 404s.

Enjoy!

Update!

To make multiple (more than two) 404’s easier, I updated the code to look like the following:

var url = window.location.href;
    
var subDirs = [
                "https://www.joehxblog.com/tags"
            ];
            
for (i = 0; i < subDirs.length; i++) {
    subDir = subDirs[i];
    
    var isTagSubdirectory = url.search(subDir);
    
    if (isTagSubdirectory > -1) {
        window.location.replace(subDir.concat("/404.html"));
    }
}

Just put all the subDirs in the JavaScript array subDirs. Careful! Make sure you make the custom 404 page, otherwords you might end up with endless forwards. Also, if you have too many custom 404’s, this script might slow down. Perhaps sort subDirs manually and use a binary search instead of the simple for loop?