404 ‘file not found’ error page for GitHub pages and Middleman

How to setup a custom 404 page for a site generated by Middleman and hosted on GitHub pages.

The 404 ‘file not found’ error is generated when a user-agent attempts to access a document that does not exist. It is helpful to redirect these errors to a document that can explain to someone that there is no document at the address they were accessing. It’s an added bonus if you can provide them with a way to find the document for which they were looking.

GitHub pages doesn’t support server redirects. GitHub does support a custom ’file not found‘ error page but it must be named 404.html or 404.md.

Directory indices

Since the file must be named 404.html or 404.md; if you’re using directory indices, they need to be turned off for the 404.html file (https://example.com/404/ and https://example.com/404 will just redirect users to GutHub’s own 404 page. So assuming that you’re using 404.html, add the following to your config.rb file:

page '/404.html', directory_index: false

If you’re using the middleman-blog extension, the directory indices settings—including the above—need to follow (rather than precede) the blog settings for them to work with pages generated by the blogging extension.

application/xhtml+xml

Due to my utopian, and contrarian, nature I am still banging a tiny drum for X.H.T.M.L. served with the proper mime-type.

GitHub does not support using a file called 404.xhtml (though they are looking at it) and bases its mime-types on the extension of files so the error page needs to be a document with the extension .html document. For this I use a separate 404_layout.rb file with the mark-up tweaked for style-sheets via a link element and declaring the encoding using a meta tag.

Relative links

Because GitHub pages is not using a server redirect for your custom page, you can’t use relative links as they will only work when you access the page directly: example.com/404.html.

Instead, the template and the layout file must use absolute links to assets (images, style-sheets &c.) as well as to other pages on your site.

Wrap-up

I haven’t bothered with the content of the 404 document itself, since that is dependent on the existing navigational elements of your site.

I think you should include both a reference to “file not found” and “404” in the title, since those terms should be familiar to many users.

An ability to search the site and possibly a replication of any archive page are also good ideas for content.

Avoid being too adamant that it’s the user’s fault or being too passive aggressive—surprisingly, those are quite common for the content of 404 pages.

My own is inexcusably terse: Fear Goidte’s 404 but I have an archive link on my site-wide navigation menu and not enough content to warrant an ability to search the site from within the site.