For the recent redesign of my blog, I noticed the need to manually set up a 404 page in Hexo.js. Here’s an instruction on how to do it.

The theme you see is a redesign I recently made. I’ve been using Hexo.js for my blog since 2017, and I like it for its ease of use. It’s great for generating a simple blog from Markdown files - which is all I need.

Since I was writing a custom theme, I dove deep into the features and capabilities of Hexo.js. To my surprise, the documentation didn’t suggest how to set up a 404 page in case the queried URL isn’t available.

After a quick search, I came across a satisfactory workaround.
You can set up a redirect with an .htaccess file, provided that you’re using web hosting that is using an Apache server.

I assume you also have a Hexo blog and came across this post because you’re facing the same issue. In case you’re using a different hosting solution, I’m sure you can find a similar workaround for NGINX or providers like Github Pages and Vercel.

Instruction

Step 1

In your /source folder, create a 404.md file with the following content:

---
title: "404: Page not found"
---

This will generate a minimal page (404.html at the root of your public folder), only showing a “404” headline. Feel free to add additional content below in the main section.

Step 2

Create or open the existing .htaccess file in your root folder. You can also create the file locally and push it to your production/live environment after you make the changes.

Add the following at the top of the file:

ErrorDocument 404 /404.html

This will reference the HTML file created in Step 1.

You can do the same thing for any error you want to cover by changing the error code and creating additional files, like so:

ErrorDocument 500 /500.html

Step 3

Run hexo generate in your project to generate the new files in your /public folder.

Step 4

Upload all your files to your production environment. If you created the .htaccess file, ensure it’s in the root folder (where your blog’s index.html is located).

Assessment

As most blogging engines and platforms come with the option for custom error pages, this is less of a feature but more of a core requirement that Hexo.js should support out of the box.

Please leave a comment or a Reaction below if this helped you.