Multilingual Docs with Jekyll Collections and Smart Navigation

Why Use Jekyll Collections for Documentation

Jekyll collections allow you to group content beyond standard posts and pages. They’re perfect for structured documentation because you can control order, metadata, and navigation more easily. Combining this with multilingual support creates an elegant and scalable system.

Core Benefits

• Organized content structure (e.g. tutorials, changelogs, API docs)
• Supports language segmentation
• Enables dynamic TOC, related items, and search

Step 1: Define the Collection

Edit your _config.yml to define your multilingual documentation collections:

collections:
  docs:
    output: true
    permalink: /:collection/:path/
defaults:
  - scope:
      path: ""
      type: docs
    values:
      layout: doc
      lang: en

Now create folders for each language under _docs:

_docs/
├── en/
│   ├── getting-started.md
│   └── advanced-features.md
├── id/
│   ├── mulai.md
│   └── fitur-lanjutan.md

Each file includes front matter like:

---
title: "Getting Started"
lang: en
tags: [intro, basics]
order: 1
---

Step 2: Create Language-Aware Navigation

To render dynamic navigation, filter collections by language:

{% assign current_lang = page.lang %}
{% assign localized_docs = site.docs | where: "lang", current_lang | sort: "order" %}

<nav class="toc">
  <ul>
    {% for doc in localized_docs %}
    <li><a href="{{ doc.url }}">{{ doc.title }}</a></li>
    {% endfor %}
  </ul>
</nav>

Step 3: Enable Multilingual Related Content

Just like in previous articles, filter by language and shared tags:

{% assign related_docs = site.docs | where: "lang", page.lang %}
{% assign shared_tags = page.tags %}
{% assign suggestions = related_docs | where_exp: "item", "item.url != page.url and item.tags | intersection: shared_tags | size > 0" %}

Limit to 3–5 suggestions:

{% for suggestion in suggestions limit:5 %}
  <li><a href="{{ suggestion.url }}">{{ suggestion.title }}</a></li>
{% endfor %}

Step 4: Integrate Search for Documentation

As before, create a multilingual index for your docs collection:

---
layout: null
permalink: /search-docs-{{ page.lang }}.json
---
[
  {% assign docs = site.docs | where: "lang", page.lang %}
  {% for doc in docs %}
    {
      "title": "{{ doc.title | escape }}",
      "url": "{{ doc.url }}",
      "excerpt": "{{ doc.content | strip_html | truncate: 160 | escape }}",
      "tags": "{{ doc.tags | join: ', ' }}"
    } {% unless forloop.last %},{% endunless %}
  {% endfor %}
]

Load this into Lunr/ElasticLunr just like previous examples, but point to /search-docs-id.json or /search-docs-en.json.

Step 5: Add Section Anchors and Dynamic TOC

You can use JavaScript to generate a table of contents from headings within each doc:

<div id="auto-toc"></div>

<script>
const headings = document.querySelectorAll('h2, h3')
const toc = document.getElementById('auto-toc')

headings.forEach(h => {
  const id = h.id || h.textContent.trim().toLowerCase().replace(/\s+/g, '-')
  h.id = id
  const link = document.createElement('a')
  link.href = '#' + id
  link.textContent = h.textContent
  toc.appendChild(link)
})
</script>

Optional: Language Switcher

If you name your files similarly (e.g. getting-started.md and mulai.md), you can map languages manually using a YAML data file like _data/doc_links.yml:

getting-started:
  en: /docs/getting-started/
  id: /docs/mulai/

Then in layout:

{% assign doc_key = page.url | split: '/' | last %}
{% assign map = site.data.doc_links[doc_key] %}
{% if map %}
  <a href="{{ map.id }}">Bahasa Indonesia</a>
{% endif %}

Real Use Case: Building a Knowledge Base

Let’s say you run a multilingual SaaS product with English and Indonesian docs. This setup allows you to:

• Link contextually between related topics in the same language
• Offer dynamic search per language
• Maintain a clean, SEO-optimized structure
• Deploy easily on GitHub Pages with zero backend

Next Step: Interactive Elements and Feedback Loops

Next, we’ll explore how to capture user behavior using JavaScript — like tracking clicks on search results and related posts — to improve relevance over time and better understand what users engage with.

Siap lanjut ke bagian pelacakan interaksi pengguna?