Breadcrumb is the term used describing the current page position in the site hierarchy by means of links. It provides orientation during site navigation.

Presentation template

Breadcrumb presentation template is defined in the _includes/base/breadcrumbs.html file.

Breadcrumb presentation template takes the page url as reference to build the hierarchy of links, starting with the Home page link.

Configuration file

Breadcrumb presentation template reads configuration variables from configuration files described below:

1. Site’s configuration file:

   _config.yml
   

   Set default values for both site and page-specific configuration variables.

2. Page preamble section of markdown files:

   **/*.md
   

   Set custom values for page-specific configuration variables. Page configuration variables defined in page preamble section of markdown files override page configuration variables defined in site’s configuration file.

Configuration variables

Breadcrumb configuration variables are described in the following table:

Showing breadcrumb at page level

To show breadcrumb in specific pages, edit the page markdown files and set the with_breadcrumbs configuration variable to true in the page preamble, as described in the example below:

---
title: This is a page with breadcrumb

with_breadcrumbs: true
---

Page content.

Showing breadcrumb at site level

To show breadcrumb in all site pages, edit the site configuration file (e.g., _config.yml) and set with_breadcrumbs configuration variable to true under defaults values, as described in the example below:

---
defaults:
  - scope:
      path: "" # an empty string here means all files in the project.
    values:
      with_breadcrumbs: true

Hiding breadcrumb at page level

To hide breadcrumb from specific pages, edit the page markdown files and set the with_breadcrumbs configuration variable to false in the page preamble, as described in the example below:

---
title: This is a page without breadcrumbs

with_breadcrumbs: false
---

Page content.

Hiding breadcrumb at site level

To hide breadcrumb from all site pages, edit the site configuration file (e.g., _config.yml) and set with_breadcrubs configuration variable to false under defaults values, as described in the example below:

---
defaults:
  - scope:
      path: "" # an empty string here means all files in the project.
    values:
      with_breadcrumbs: false

Related topics