Handling 404 errors with Octopress

Stardate 56782.2 (Sun May 4, 2014 10:03 am) in Code Code, Ruby, Octopress

Building a blog with Octopress can be a bit of a hassle at times. Having converted from Wordpress, I miss the “Page not found” error that Wordpress provides when you get a request for an invalid URL. Thankfully, with Apache, htaccess and a touch of code, you can create your own 404 page.

First off, create a new page in your source folder. I call mine errors/404-page-not-found.html. That creates a corresponding HTML document in /errors/404-page-not-found.html. There aren’t any restrictions on the filename, but you must keep the extension as a HTML. If you leave it as a markdown file, then the Jekyll engine tends to strip out the HTML tags and leaves you with just the inner code.

404 page

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


---
layout: page
title: "404 page not found"
comments: false
sharing: false
footer: false
---

{% img center /images/404.jpg %}

<style type="text/css">
  /* avoid to display the page's title, it kinda give it all away */
  [role=article] > header {
      display: none;
  }
</style>

You’ll also need to change the sitemap_generator plugin to exclude the generated 404 page from the sitemap XML.

Sitemap plugin

diff --git a/plugins/sitemap_generator.rb b/plugins/sitemap_generator.rb
index a08590b..92cb0dd 100644
--- a/plugins/sitemap_generator.rb
+++ b/plugins/sitemap_generator.rb
@@ -46,7 +46,7 @@ module Jekyll
   SITEMAP_FILE_NAME = "sitemap.xml"

   # Any files to exclude from being included in the sitemap.xml
-  EXCLUDED_FILES = ["atom.xml"]
+  EXCLUDED_FILES = ["atom.xml", "404-page-not-found.html"]

   # Any files that include posts, so that when a new post is added, the last
   # modified date of these pages should take that into account

Finally, you need to tell Apache to serve up this page when it encounters a 404 error. Create a file source/.htaccess with the following contents.

.htaccess

ErrorDocument 404 /errors/404-page-not-found.html

This should be all you need.

Thanks to kAworu for the steps to build this page.