Highlight Search Terms in Multilingual Jekyll

Why Highlighting Matters in Search UX

When users land on a page after searching, they often need to visually locate where their search keywords appear. This becomes especially important in long-form documentation or blogs. By automatically highlighting those terms, you improve usability, reduce bounce rate, and guide users directly to the content they care about.

For multilingual sites, this requires extra care — search terms may appear in different languages, and the highlights must respect the page’s language context.

Step 1: Pass Search Terms via URL

When users perform a search (e.g., using Lunr.js or Simple-Jekyll-Search), include the search query in the resulting URL. This is often done like this:

https://example.com/docs/page.html?q=installation

Or for multilingual:

https://example.com/es/guias/instalacion?q=instalación

This lets the destination page know what word to highlight dynamically using JavaScript.

Step 2: Add a Highlight Script Include

Create an include file _includes/highlight-search.js:

<script>
(function() {
  const queryString = new URLSearchParams(window.location.search);
  const term = queryString.get('q');
  if (!term) return;

  const highlight = (text, keyword) => {
    const regex = new RegExp("(" + keyword.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + ")", "gi");
    return text.replace(regex, '<mark>$1</mark>');
  };

  const walk = (node) => {
    if (node.nodeType === 3 && node.nodeValue.trim().length) {
      const span = document.createElement("span");
      span.innerHTML = highlight(node.nodeValue, term);
      node.replaceWith(span);
    } else if (node.nodeType === 1 && node.childNodes) {
      node.childNodes.forEach(walk);
    }
  };

  document.addEventListener("DOMContentLoaded", () => {
    document.querySelectorAll("article, .content, .main").forEach(container => {
      walk(container);
    });
  });
})();
</script>

This script searches for the keyword from the URL query and highlights all matching instances inside the main content.

Step 3: Include the Script in Layout

Add the script include to your layout (e.g., in _layouts/default.html):

{% raw %}
{% include highlight-search.js %}
{% endraw %}

This ensures the highlighting works on any page the user lands on from a search result.

Step 4: Language-Aware Search Indexing

When building your search index (using Lunr.js or similar), make sure each language has its own version. You can maintain a search.json per language:

/search_en.json
/search_es.json

Configure your search bar to redirect users to the correct language path with the query term:

location.href = "/es/busqueda/resultados.html?q=" + encodeURIComponent(term);

Step 5: Prevent False Matches

You may want to avoid highlighting inside <code>, <pre>, or navigation elements. Modify the script to skip these tags:

if (node.nodeType === 1 && !['SCRIPT','STYLE','CODE','PRE','NAV'].includes(node.tagName)) {
  node.childNodes.forEach(walk);
}

Step 6: Style the Highlight

Add CSS to your site’s stylesheet:

mark {
  background-color: yellow;
  padding: 0 2px;
  border-radius: 2px;
}

For dark themes:

mark {
  background-color: #ffc107;
  color: #000;
}

Use Case: Multilingual Docs

Imagine your Spanish documentation has technical terms like “instalación” or “configuración”. A user searches "instalación de plugins" and lands on a guide. With highlighting, they immediately see the term emphasized, saving time and frustration.

Search Term Variants

• Allow support for plural forms, e.g., "configuraciones"
• Support accents and diacritics using normalize() in regex
• Consider stemming in multilingual search engines

Advanced: Multiple Keywords

To support multiple words:

const terms = term.split(/\s+/).filter(Boolean);
const regex = new RegExp("(" + terms.join("|") + ")", "gi");

This highlights all parts of a compound search like "plugin instalación rápida".

Highlighting search terms in Jekyll improves the reader’s journey, especially in multilingual setups. It guides attention and helps users validate they’ve found the right content. With just a little JavaScript and structured query handling, you can bring this feature to your GitHub Pages site.

In the next article, we’ll explore how to use client-side filters and toggles to allow users to dynamically adjust views within a multilingual Jekyll site — all without reloading the page.