Skip to content

Latest commit

 

History

History
47 lines (32 loc) · 2.54 KB

HowBreadCrumbsWork.md

File metadata and controls

47 lines (32 loc) · 2.54 KB
Raw

How Breadcrumbs Work

Setting or updating breadcrumbs

Page-level breadcrumbs are managed by _plugins/breadcrumbs.rb. The breadcrumbs plugin makes it possible to use the {% breadcrumbs %} Liquid tag. breadcrumbs.rb looks for or generates breadcrumbs in this order:

  1. Looks for default path-level breadcrumb settings in _config.yml
    • Each path can support an unlimited number of breadcrumbs.
    • These breadcrumbs must be named breadcrumb_[n] where [n] is the position breadcrumb trail, for example: breadcrumb_1, breadcrumb_2, or breadcrumb_3
  2. If no default breadcrumb was set in _config.yml, breadcrumbs will be generated from the file's path or URL.
    • _plugins/breadcrumbs.rb splits the URL string into an array by the /
    • Each segment in the path becomes a new breadcrumb, that links to its corresponding URL path.
    • The humanize method splits the path segment by -, and capitalizes each word in the segment. If there's a word that shouldn't be capitalized, add it to filterwords.

To add or customize the text of a breadcrumb, edit _config.yml.

Breadcrumbs and URLs

The breadcrumbs plugin uses the structure of the URL to do two things:

  1. To function as the titles of the breadcrumbs if those titles haven't been set in _config.yml
  2. To determine how many breadcrumb segments there should be.
    • There will only ever be as many breadcrumbs as there are URL segments.
    • The last breadcrumb is always the page title, as defined by the title property in the YAML data of the Markdown file.

For example, the URL https://vets.gov/employment/job-seekers/alternative/ has three path segments (not including the base URL of vets.gov):

  1. /employment/
  2. /job-seekers/
  3. /alternative/

That page should have a tri-level breadcrumb that reads: Employment > Job Seekers > Alternative ways to start your career. However, we've used _config.yml to override the text for the first breadcrumb.

To override the text of a breadcrumb level, update _config.yml with lines similar to what follows.

- scope:
    type: "employment"
  values:
    breadcrumb_1: "Careers and Employment"
    layout: "page-breadcrumbs"
    body_class: "page-employment"

Here, we're overriding the breadcrumb text that was generated by the URL with the value of breadcrumb_1.

In order to update the last breadcrumb, you must update the title property that's part of the YAML metadata for the corresponding file.

Adding another breadcrumb requires adding another sub-directory or segment to the URL path.