Fine Tuning Pelican: Custom Error Pages

Preface¶

This is one of the articles in a series about how I fine tuned my Pelican+Elegant web site to make it “more mine”. For other articles in the series, click on the title of the article under the heading “Fine Tuning Pelican” on the right side of the webpage.

Unlike my series on Choosing and Setting Up Pelican, these articles are intended to be byte sized, addressing specific fine tunings I made to my own website. As such, the first article in this series contains a Disclaimer section with generic information for each of the articles in the series.

Introduction¶

When a webpage is requested that does not exist, it is common for websites to react to the request by displaying a custom error page. While Pelican does not natively ship with this feature, Elegant adds a themed page that does. This article details the changes needed to mark Elegant’s custom error page is properly used as “the” error page.

Configuring Elegant and GitHub Pages¶

Following the instructions from the Elegant Documentation, Elegant can be instructed to generate a properly themed 404 page by adding the 404 string to the DIRECT_TEMPLATES variable in the pelicanconf.py file. After following those instructions, the next time the website is generated, a 404.html file will be generated in the base directory. This file will have all of the trappings of the Elegant theme, and it will display an error page that includes a box to search for what the reader was looking for.

The website hosting service that is being used will dictate if there are any extra steps needed to enable the custom 404 page. For GitHub Pages, as long as the file is named 404.html and is in the root directory that is being hosted, GitHub will automatically pick it up and use it as the 404 error page. Note that it seems like the file must exist on the master branch of the GitHub Pages directory in order for that action to take effect.

Using Other Themes¶

If you are using a theme other than Elegant, you can replicate some of the behavior that Elegant provides out of the box. In particular, you can define a page called markdown.md somewhere in your contents, and add the following text to it:

---
Title: My Custom Page
permalink: /404.html
---

This is my custom error page.

The key to this being used as an error page is the permalink: /404.html part of the markdown header. This informs Pelican to always publish the page with output file of /404.html, placing it in the root directory where it will be picked up properly by many site publishers, such as GitHub Pages.

What Was Accomplished¶

In this article, I provided some quick information on how to set up a custom 404 page using Elegant, and noted how it will be picked up by GitHub Pages. I also provided some basic information on how to set up a custom page for themes other then Elegant. By using this approach, I was able to have a custom error page that had the theme of my website, allowing the reader to recover in case of a bad URL.

Like this post? Share on: Twitter ❄ Facebook ❄ Email