How to Use Underscores with Github Pages

TLDR: Github pages was originally built to serve assets created with Jekyll. It will treat files and directories named starting with an underscore as special and won’t serve them. You can switch this behaviour off by adding a ‘.nojekyll` file at the root of your github pages repo.

Last night I updated this blog to use Astro as its build tool. I’ve been using it for my project mixes.it for some time so thought it would make sense to consolidate and move over to it. The move to Astro actually took me some time to do and I’m going to write about that side of things in a future post. The thing I’m going to write about here is the frustrating time I had deploying the final build to Github pages.

I started late yesterday afternoon thinking - “I probably should leave this deployment for another day, but it’s just a simple static site”. In hindsight I was right and deployment was particularly annoying. Let this serve as a cautionary tale to listen to yourself.

The Problem

The problem is caused by two things: firstly the way assets built with Astro can default to using underscores in their names. This is actually rollup.js under the hood naming things based on Astro routes. If you name a route using square braces and build, this could result in an asset that rollup will name starting with an underscore as below.

It looks to me like Astro defaults to the name used for the first route file it encounters and rollup replaces square braces with underscores.

Unfortunately this causes an issue when deploying to Github pages. By default all files and folders beginning with an underscore hosted there are ignored as they are assumed to be special file reserved for Jekyll.

Switching off Jekyll on Github Pages

The solution is really simple when you know it. You can switch off jekyll completely on github pages by using an empty ‘.nojekyll’ file at the root of your Github pages repo as outlined by Tom Preston-Werner in 2009. Once this is done assets starting with underscores will be served as you might expect.

It took me several hours to find this - hope it saves you some time!