How to implement breadcrumbs on a Jekyll site with nested categories

Hierarchical categories and breadcrumbs

Last modified:
Tags Git , Server , Bare-Repository


One of the ways to structure content in a Jekyll environment is to put posts in subdirectories, where each subdirectory becomes a category of the post.

For example, the post in this directory structure /docs/science/_posts/ automatically gets the categories docs and science.

└── docs
    └── science
        └── _posts

Then a breadcrumb included in each post/category layout, can automatically generate a link to each path of the structure

The breadcrumbs code should be placed at /_includes/breadcrumbs.html:

	{% assign categories = include.path | split:"/" %}
	{% assign filename_without_extension = categories | last | split:"." | first %}
	{% if categories contains "_posts" or filename_without_extension == "index" %}
	{% comment %} posts are like /docs/python/_posts/ {% endcomment %}
	{% comment %} OR pages are index.* i.e.: like /docs/python/ or index.html {% endcomment %}
	{% assign categories = categories | pop %}
	{% endif %}

	{% assign route="" %}

	<a href="{{ '/' | absolute_url }}">Home</a>
	{% for category in categories %}
	<span class="prompt">>></span>
	{% assign route = route | append: '/' | append: category %}
	{% if forloop.last %}
	{% if include.title %}{{include.title}}{% else %}{{ category }}{% endif %}
	{% else %}
	<a href="{{ route | absolute_url }}">{{ category }}</a> 
	{% endif %}
	{% endfor %}

Posts layouts

Each layout used in category pages and posts should include the breadcrumbs.html code, with the current page path and title parameters.

In /_layouts/post.html:

{% include breadcrumbs.html path=page.path title=page.title %}


The previous scheme would generate the following breadcrumb for each case.

URLGenerated BreadcrumbServed Filename
/docshome > docsdocs/
/docs/sciencehome > docs > sciencedocs/science/
/docs/abouthome > aboutdocs/
/docs/science/my_titlehome > docs > science > my titledocs/science/_posts/
If page does not have a *title* variable in front matter, then its filename will be displayed in breadcrumbs.

You can see this in action in the jekyll-skeleton example website.

Marcelo Canina
I'm Marcelo Canina, a developer from Uruguay. I build websites and web-based applications from the ground up and share what I learn here.
comments powered by Disqus

How to generate a list with links for each category when using hierarchical categories in Jekyll

Clutter-free software concepts.
Translations English EspaΓ±ol

Except as otherwise noted, the content of this page is licensed under CC BY-NC-ND 4.0 . Terms and Policy.

Powered by SimpleIT Hugo Theme