BuzzPathRank

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...

Why Deep Linking Matters in Multilingual Content Deep linking allows users to link directly to specific sections of a page. In documentation, tutorials, and knowledge bases, this enhances shareability, SEO, and user navigation—especially when working with multilingual content. For example, a user reading the Spanish version of a guide should be able to link directly to a section like "Instalación" and land on that exact heading, not its English counterpart. This behavior also encourages content reuse and seamless collaboration across language teams. Challenge: Language-Dependent Anchors The challenge is keeping section anchors consistent or mirrored across translations. Most Jekyll setups use the heading text (slugified) as the id , which changes by language. So the anchor #setup in English might become #instalacion in Spanish. We’ll solve this by assigning custom, language-agnostic IDs to each section using data files or consistent keys. Step 1: Use Language...

Improving UX with Scroll-Aware TOC After building a multilingual table of contents (ToC) in the previous article, it's time to enhance usability further. A scroll spy highlights the current section in the navigation menu as the user scrolls, making it easier to track their reading position—especially in multilingual content where users might skim differently based on text length or structure. We'll use the modern IntersectionObserver API for a performance-friendly implementation that avoids scroll event bottlenecks. Understanding the Scroll Spy Behavior The goal is to dynamically highlight the currently visible section in the ToC. This involves: Detecting when a heading (h2, h3) enters the viewport Finding the corresponding link in the ToC Adding/removing an active class to style the link Step 1: Update Your TOC Markup In your _includes/toc.html , make sure the anchor tags have a consistent structure. Each should wrap a heading's ID: <li...

Why a Multilingual Table of Contents Matters Longform content needs a navigable structure to help users skim and understand context. In multilingual websites, it's not enough to generate a generic ToC—you need to respect the language of the user, label sections accordingly, and ensure the experience remains consistent across locales. In this tutorial, we’ll build a reusable, dynamic table of contents system for Jekyll posts that adapts based on language, using Liquid for static structure and JavaScript for client-side interaction. Planning the Multilingual Navigation We want to achieve the following: Detect headings within the article content Generate anchor links with readable text in the correct language Enable smooth scrolling Make it reusable across all posts We'll separate content logic from layout logic using includes and data-driven design. Step 1: Add Headings with ID Attributes Make sure your headings have an `id` attribute for linking. I...

Why Client-Side Multilingual Search Matters Search is a critical feature of any knowledge base or blog. In multilingual setups, it's not enough to simply list content by tag or category—users want to search in their language. However, most search engines or plugins don't support client-side indexing and filtering for multilingual content out of the box. This article shows you how to use Lunr.js to build a fast, client-side search feature that respects language boundaries in a Jekyll-based multilingual site. How Lunr Works in Jekyll Lunr is a JavaScript-based full-text search engine for the browser. In Jekyll, you typically build a search index during the build process, then load that JSON file on the frontend. We’ll go further by generating multiple indexes—one for each language—and dynamically selecting the correct one based on the current language context. Folder and Language Structure Assume a structure like this: ├── _resources │ ├── en │ └── es ├── s...

Why Localized Navigation Matters When building a multilingual site, it’s common to translate content. But what about navigation structures like categories and tags? If users switch to a different language, the taxonomy must follow. Showing English tags on a Spanish page creates confusion and breaks consistency. In this guide, we’ll show how to create a tag-category navigation structure in Jekyll that automatically adapts based on the current language context. The solution works without JavaScript, external plugins, or third-party CMS—just plain Liquid, YAML, and data-driven design. Site Structure for Multilingual Content We’ll assume you have a language-aware directory structure: ├── _config.yml ├── _data │ └── navigation.yml ├── _resources │ ├── en │ │ └── optimizing-includes.md │ ├── es │ │ └── optimizacion-includes.md Each document contains language-specific lang , category , and tags metadata. --- title: Optimizing Includes lang: en category: perform...