Add a Custom 404 Page to Jekyll on GitHub Pages

The default 404 page is a dead end. A small custom page can keep the site’s navigation, explain what happened, and give people somewhere useful to go next.

GitHub Pages serves 404.html from the root of the generated _site directory. The simple Jekyll approach is to add 404.md or 404.html at the root of the source project:

---
layout: page
title: 404
---

# Page not found

The page may have moved. Try the navigation above or return to the [home page](/).

Jekyll processes the front matter, applies the page layout, and generates the required /404.html file.

When the source file lives elsewhere

If you organise pages in subdirectories, set the output path explicitly:

---
layout: default
permalink: /404.html
---

# Page not found

The page you requested does not exist.

The permalink keeps the generated file at the site root regardless of where the source file lives.

Keep this page useful and light. A clear message, a home-page link, and the site’s normal navigation usually do more than an elaborate joke that leaves the visitor equally lost.

← Back to all articles