Buy me a coffeeBuy me a coffee

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


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.

URL Generated Breadcrumb Served Filename
/ home index.html
/docs home > docs docs/
/docs/science home > docs > science docs/science/
/docs/about home > about docs/
/docs/science/my_title * home > docs > science > my title docs/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.