Learning that Github Pages Struggles with Certain File Names

Recently I made a new contribution to a project called fast-dna, which included a build script that generated various pages for their documentation site. However, soon after landing the last bit of the script, a new bug appeared in the project’s documentation. Routing to certain pages gave a familiar error.

Testing locally, nothing like this every happened; I’d build the site with the script, load it, and could route to ever page generated. What gives? Obviously it looked like there was a problem with how the project was built into production.

At first I thought the problem was caused by a different file structure in the development and build/production versions of the docsite, since the two are in fact different; however this wasn’t the case.

The error was caused by Jekyll, which Github Pages is deeply integrated with. If you don’t know what Jekyll is, in brief it is a static website generator that uses markup to generate its pages.

But how did Jekyll cause this issue? It’s pretty simple really; it won’t build some types of files or directories that follow some specific formats , namely files/directories that are:

  • used for backup, using ~ , . or #
  • used to contain site content, so they start with an underscore(_ )
  • are excluded in the site configuration

The pages I couldn’t route to, surprise surprise, started with _ . So when the docsite was being built these files were being ignored. When running the site locally it wasn’t using Github Pages, which explains why it was working at that moment.

So at this point the question is; how could an issue like this be fixed? There were literally hundred of these files that had this naming convention, and finding a way to rename them all or change their formatting didn’t seem viable.

Thankfully there are ways to force jekyll to not ignore these types of files. If a .nojekyll or _config.yml file is included in the root project folder, files that start with underscores can be recognized. So for me a _config.yml file with the following is all that’s really needed in this specific scenario.

- "_*_.html"
- "_*_.*.html"

The doc site was created with something called Docusaurus. This made me a bit nervous at first because with Docusaurus you don’t have full control over your final build folder, so I wasn’t sure if permanently adding something like this to root was even possible. However, it is in fact do-able if a file is added to the website/pages folder, anything there will get built into the root folder of the final build by default.