Multilingual Breadcrumb Navigation in Jekyll

Why Breadcrumb Navigation Matters

Breadcrumbs provide a visual map of where the user is within your site's content hierarchy. They're useful for long documentation, nested pages, and blog categories. For multilingual sites, breadcrumbs should reflect the language of the current page and the translated structure.

For example, instead of always showing:

Home > Guides > Installation

The Spanish version should show:

Inicio > Guías > Instalación

This not only improves user experience but also helps search engines understand your site structure in multiple languages.

Step 1: Define Page Hierarchies

Each page should define its parent(s) in the front matter. You can use a custom field like breadcrumbs with unique IDs:

breadcrumbs:
  - home
  - guides
  - installation

This list forms the trail from the homepage to the current page. These IDs will be used for translation and linking.

Step 2: Prepare Translations

Add a breadcrumbs section in each language’s translation data file:

# _data/translations/en.yml
breadcrumbs:
  home: "Home"
  guides: "Guides"
  installation: "Installation"

# _data/translations/es.yml
breadcrumbs:
  home: "Inicio"
  guides: "Guías"
  installation: "Instalación"

These keys match the breadcrumb IDs declared in each page’s front matter. This keeps your translations clean and maintainable.

Step 3: Create the Breadcrumb Include

Create an include file _includes/breadcrumbs.html:

{% raw %}
{% if page.breadcrumbs %}
  <nav class="breadcrumbs" aria-label="Breadcrumb">
    <ul>
      {% for crumb in page.breadcrumbs %}
        <li>
          <a href="{{ site.baseurl }}/{% if crumb != page.breadcrumbs.last %}{{ site.data.routes[page.lang][crumb] }}{% endif %}">
            {{ site.data.translations[page.lang].breadcrumbs[crumb] }}
          </a>
        </li>
      {% endfor %}
    </ul>
  </nav>
{% endif %}
{% endraw %}

This loop renders the breadcrumb items with language-specific labels and links. You’ll need a routing data file to define the URL paths.

Step 4: Add Route Mappings per Language

Create route mapping files like _data/routes/en.yml:

home: ""
guides: "guides"
installation: "guides/installation"

# _data/routes/es.yml
home: "es"
guides: "es/guias"
installation: "es/guias/instalacion"

This allows your breadcrumb links to correctly point to the translated version of each page.

Step 5: Include Breadcrumbs in Your Layout

Edit your layout file, e.g., _layouts/default.html, and include the breadcrumb:

{% raw %}
{% include breadcrumbs.html %}
{% endraw %}

Place it before the main content so users immediately know where they are.

Step 6: Add Structured Data for SEO

You can add schema.org markup to help search engines display breadcrumb paths in search results:

{% raw %}
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "BreadcrumbList",
  "itemListElement": [
    {% for crumb in page.breadcrumbs %}
      {
        "@type": "ListItem",
        "position": {{ forloop.index }},
        "name": "{{ site.data.translations[page.lang].breadcrumbs[crumb] }}",
        "item": "{{ site.url }}/{{ site.data.routes[page.lang][crumb] }}"
      }{% unless forloop.last %},{% endunless %}
    {% endfor %}
  ]
}
</script>
{% endraw %}

This enhances visibility in Google and helps with multilingual SEO.

Styling Your Breadcrumb

Basic breadcrumb styles:

.breadcrumbs ul {
  list-style: none;
  padding: 0;
  display: flex;
  flex-wrap: wrap;
}
.breadcrumbs li + li::before {
  content: ">";
  padding: 0 0.5em;
}
.breadcrumbs a {
  text-decoration: none;
  color: #336699;
}

Use Case: Documentation Navigation

Imagine a multilingual API documentation with 100+ pages. Breadcrumbs give users instant context, and allow devs to link directly to relevant sections while maintaining language fidelity.

They also allow content editors to reorganize documentation by just changing breadcrumb sequences without hardcoding links.

Enhancing UX and SEO

• Breadcrumbs reduce bounce rate by guiding users deeper into related content
• They help users orient themselves in complex structures
• Multilingual breadcrumbs allow better internationalization of your UX

Conclusion

With just data files and includes, you can implement flexible, multilingual breadcrumbs in Jekyll. They enhance navigation, boost search visibility, and make your content easier to explore.

In the next guide, we’ll discuss how to add search term highlighting for client-side search results to improve user orientation after navigation.