When hosting your website with Jekyll, customizing error pages like the 503 Service Unavailable page can improve user experience and provide helpful information during downtime. In this guide, you'll learn how to create a custom 503 page in Jekyll.

Understanding the 503 Service Unavailable Error

The 503 error indicates that the server is temporarily unable to handle the request. This can happen during maintenance or server overloads. Customizing this page helps inform visitors about the situation and reassures them that the issue is temporary.

Creating the Custom 503 Page

Follow these steps to create your own 503 page in Jekyll:

  • Navigate to your Jekyll project directory.
  • Create a new file named 503.html in the root folder.
  • Open 503.html in your code editor.
  • Add the following HTML structure:

Example of a simple 503.html:

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Service Unavailable</title>
<style>
body { font-family: Arial, sans-serif; text-align: center; padding: 50px; }
h1 { font-size: 50px; color: #e74c3c; }
p { font-size: 20px; }
</style>
</head>
<body>
<h1>503 Service Unavailable</h1>
<p>Our website is currently undergoing maintenance. Please try again later.</p>
</body>
</html>

Configuring Your Server to Use the Custom Page

Depending on your hosting environment, you need to tell your server to serve this custom page during downtime.

For GitHub Pages

GitHub Pages doesn't support custom error pages directly. A workaround is to use a custom 503 redirect or employ a third-party service for error handling.

For Netlify

Create a netlify.toml file in your project root with the following content:

<pre>[build]\n publish = \"_site\"\n\n[[redirects]]\n from = \"/*\"\n to = \"/503.html\"\n status = 503\n conditions = { ResponseCode = 503 }\n</pre>

Testing Your Custom 503 Page

Once configured, simulate a server error or maintenance mode to verify that your custom 503 page appears correctly. Clear your cache and try accessing your site to see the message.

Conclusion

Creating a custom 503 Service Unavailable page in Jekyll enhances user experience during server downtime. By designing a clear and helpful error page and configuring your server accordingly, you ensure visitors are informed and reassured. Regular testing ensures your page displays correctly when needed.