Breadcrumbs in Jekyll

Breadcrumbs help users locate themselves within the hierarchy of your site. While your site’s header might have some links that act as the site’s primary navigation, breadcrumbs show the user exactly where they currently are. They show the path from the home page down to the current page and provide links for moving back up the site hierarchy.

Jekyll doesn’t have any built-in support for rendering breadcrumbs for a page or post and implementing them can be tricky because GitHub Pages doesn’t let you install plugins (it only supports a small list of Jekyll plugins), so you can’t use the jekyll-breadcrumbs plugin on GitHub Pages.

I decided not to use them on my own site in the end, but the GitHub Gist below provides a couple of Jekyll template includes that implement GitHub-compatible page and post breadcrumbs.

The breadcrumbs look something like this:

Home > Posts > Example Category > 2019 > Dec > 23 > Breadcrumbs in Jekyll

The breadcrumbs are made up of:

  1. A breadcrumb for the site’s front page: Home in the example breadcrumbs above
  2. A breadcrumb for the page or post’s collection, if it has one: > Posts in the example breadcrumbs above (posts belong to the collection “posts” by default)
  3. One breadcrumb for each of the page or post’s categories, if it has any: > Example Category in the example breadcrumbs above
  4. For posts: breadcrumbs for the post’s year, month and day: > 2019 > Dec > 23 in the example breadcrumbs above
  5. Finally, a breadcrumb for the page or post’s title: > Breadcrumbs in Jekyll in the example breadcrumbs above

There are options for omitting each of the home, collection, categories, date and title components, so you can customize the breadcrumbs to look how you want. See the Gist’s README for docs.

Creating pages for breadcrumbs to link to

Breadcrumbs will automatically find and link to their corresponding pages if they exist:

Controlling breadcrumb text

Whenever a breadcrumb finds a corresponding page to link to, it also takes on that page’s title as the breadcrumb text.

For example if the page has the title “All Posts in Example Category” then “All Posts in Example Category” will appear as the breadcrumb text for the category, in the breadcrumbs of posts that belong to the category.

Or if has the title “Archive” then the post’s collection will appear as “Archive” in the breadcrumbs of posts belonging to that collection.

The title of the front page of the site (the top-level file) controls the text of the Home breadcrumb.

You can override this for any page by adding a breadcrumb_text variable to the page’s frontmatter:

breadcrumb_text: Example Category

All Posts in Example Category


Making breadcrumbs match URLs

You might want your breadcrumbs to match the /-separated parts of your permalink URLs. You can achieve this either by changing your permalink setting in _config.yml to match the default breadcrumbs or by configuring the breadcrumbs to match your permalink setting.

For example this permalink setting:

permalink: /:collection/:categories/:year/:month/:day/:title/

will make your permalink URLs match the default breadcrumbs.

Another example: if you use the built-in permalink: pretty format then adding then passing omit_collection=trueto the include will change your breadcrumbs to match your pretty permalinks:

{% include breadcrumbs.html omit_collection=true %}


The Gist

Here’s the gist, with the breadcrumbs templates and installation and usage docs: