{
  "$type": "site.standard.document",
  "description": "How to build 404 pages for Jekyll and GitHub Pages that automatically suggest similar URLs to those requested, using Levenshtein distance and your sitemap.",
  "path": "/2022/06/30/helpful-404s-for-jekyll-and-github-pages/",
  "publishedAt": "2022-06-30T04:00:00.000Z",
  "site": "at://did:plc:dw6j5wx7vyzjxxoauzdbim6w/site.standard.publication/3mn5pbyuiq52t",
  "textContent": "While the internet has long had a soft spot for clever pages, it's rare to see one that's actually helpful, especially for static sites like Jekyll or GitHub Pages that make dynamic searches more difficult. Great 404 pages should help visitors find what they're looking. Here's how I updated the (not found) pages on my own site to resolve typos and suggest other pages potentially relevant to the visitor's intended URL, in case you'd like to implement the same or similar functionality on your own site: How my 404 page suggests alternate URLs If you were to click an invalid link or typo a URL on my site, the following would occur: 1. You'd see a page[^1] 2. Your browser would retrieve and parse my site's [^2] 3. Your browser would find the valid path that has the shortest edit distance from the path you requested 4. Your browser would update the page with a link to the suggested path What it looks like Let's say you tried to navigate to a path that doesn't exist like . Along with a list of recent posts, the experience, would look something like this: The page you are trying to view does not exist. Perhaps you're looking for /2022/06/30/helpful-404s-for-jekyll-and-github-pages/? How it works This functionality is driven by a surprisingly small amount of JavaScript (really TypeScript): The v0.1 Could it be written better? Absolutely (but it works!). For now, I'm using to find the closest path to the one requested, and the lower level and to retrieve and parse the XML sitemap. Along with better error handling, this could also be implemented with the more modern API to retrieve the sitemap and something like to more properly parse the XML, but my modern JavaScript knowledge is limited.[^3] If you'd like to take a pass at a better implementation, pull requests are always welcome. Conclusion When I click on a broken link, the site that I land on should point me in the right direction. After all typo'd or updated URLs are not uncommon, and the site I'm visiting knows more about the site's content and structure than I ever will. While it's still true that everything should have a URL, sometimes those URLs change or get lost in translation. Although you might hope a visitor would never see one, great 404 pages go that extra step and help visitors find what they're looking for. If you're interested in implementing the same functionality on your own site, the code above is part of the Jekyll theme, and is licensed under The MIT License. [^1]: When a visitor tries to access a URL that does not exist, GitHub Pages will serve the file in the site's root directory, if one exists. [^2]: Generated automatically by the Jekyll Sitemap plugin. The same implementation would work with any other static site (or static site generator), so long as your site has a comprehensive . [^3]: I'm proud to say that no was harmed in the making of this functionality.",
  "title": "Helpful 404s for Jekyll (and GitHub Pages)"
}