building a documentation system using jekyll and data-driven navigation

Why Use Jekyll for Documentation

Jekyll is an ideal platform for building documentation systems due to its static architecture, version control integration, and flexible templating using Liquid. While many developers use Jekyll for blogs or portfolios, it’s equally powerful for managing extensive documentation — especially when powered by data files and custom navigation logic.

Understanding Data-Driven Navigation in Jekyll

Jekyll supports YAML, JSON, and CSV data files. These files can define a centralized navigation structure, reducing duplication and improving maintainability. This approach is especially useful when your documentation spans hundreds of pages across various sections, such as:

• Getting Started Guides
• API Reference
• CLI Tools
• Advanced Usage

Step 1: Define Documentation Sections Using Collections

Start by defining collections in your _config.yml to categorize your documentation:

collections:
  docs:
    output: true
    permalink: /docs/:path/

Now create a _docs folder and organize content with folders for each section:

_docs/
  getting-started/
  api/
  cli/
  advanced/

Step 2: Create a Navigation YAML File

In the _data folder, create docs_nav.yml:

- title: Getting Started
  url: /docs/getting-started/
  children:
    - title: Installation
      url: /docs/getting-started/installation/
    - title: Configuration
      url: /docs/getting-started/configuration/
- title: API Reference
  url: /docs/api/
  children:
    - title: Authentication
      url: /docs/api/authentication/
    - title: Endpoints
      url: /docs/api/endpoints/

Step 3: Loop Through Navigation in Layout

Use the _layouts/default.html or a custom sidebar partial to render the nav:

{% raw %}

  {% for item in site.data.docs_nav %}
    

      {{ item.title }}
      {% if item.children %}
        

          {% for child in item.children %}
            
{{ child.title }}
          {% endfor %}
        
      {% endif %}
    
  {% endfor %}

{% endraw %}

Step 4: Build a Table of Contents Automatically

To improve navigation within a long documentation page, you can generate a Table of Contents (ToC) dynamically using JavaScript or a plugin like jekyll-toc.

Install it via your Gemfile:

gem 'jekyll-toc'

Then add this in your layout:

{% raw %}{{ content | toc }}{% endraw %}

Case Study: Internal Developer Docs for a SaaS Startup

An internal team at a fast-growing SaaS company used Jekyll and GitHub Pages to build their developer documentation. They relied on:

• Custom collections for CLI, APIs, and Tutorials
• Centralized navigation with data files
• Global versioning via branches and front matter

The result was a blazing-fast, Git-friendly documentation hub accessible to devs company-wide. Using pull requests, teams could suggest edits that were previewed via Netlify before merging.

Step 5: Adding Versions to Documentation

Support multiple documentation versions using URL prefixes:

collections:
  v1:
    output: true
    permalink: /docs/v1/:path/
  v2:
    output: true
    permalink: /docs/v2/:path/

Then mirror your content in _v1 and _v2 folders, and adjust the navigation file accordingly. You can dynamically show the version using page.collection.

Step 6: SEO Best Practices for Documentation

• Use clear and consistent permalinks with hyphens
• Include meta descriptions in front matter
• Generate a sitemap that includes all collection pages

Step 7: Creating a Searchable Index

To make the docs searchable, generate a JSON index across all collections:

---
layout: null
---
[
  {% raw %}{% assign docs = site.docs | concat: site.v1 | concat: site.v2 %}{% endraw %}
  {% raw %}{% for doc in docs %}{% endraw %}
    {
      "title": {% raw %}"{{ doc.title | escape }}",{% endraw %}
      "url": {% raw %}"{{ doc.url }}",{% endraw %}
      "content": {% raw %}"{{ doc.content | strip_html | strip_newlines | escape }}" {% endraw %}
    }{% raw %}{% if forloop.last == false %},{% endif %}
  {% endfor %}
]

Conclusion

Jekyll’s flexibility with collections and data files enables you to build robust, scalable documentation systems. By using data-driven navigation, versioning via collections, and client-side search, your documentation remains maintainable even as your project grows. Whether it’s for internal devs or external users, this approach provides both performance and usability without needing a CMS.