jekyll versioned docs routing

By -

Versioning documentation is essential when your product evolves, especially if breaking changes occur between releases. Users may be on different versions and need access to the documentation that matches their deployed software. Jekyll offers a lightweight way to organize and serve versioned content using folder-based routing.

Common Use Cases

  • APIs that release breaking changes per version
  • Software libraries with long-term support (LTS) releases
  • Educational material where previous versions need to remain accessible

Folder-Based Routing Strategy

The simplest way to manage versions in Jekyll is by creating separate folders for each version of the documentation inside a root directory like /docs.

docs/
├── v1.0/
│   ├── index.md
│   ├── installation.md
│   └── api.md
├── v2.0/
│   ├── index.md
│   ├── installation.md
│   └── api.md

Permalink Control

You can define permalinks in front matter for clean URL generation:

---
title: "API Reference"
permalink: /docs/v1.0/api/
layout: doc
---

Default Version Redirection

Use the root /docs to redirect to the latest version:

---
redirect_to: /docs/v2.0/
---

Automating Navigation Between Versions

Create a global navigation that allows users to switch versions easily. Define available versions in _data/versions.yml:

- version: v1.0
  path: /docs/v1.0/
- version: v2.0
  path: /docs/v2.0/

Dynamic Version Switcher

In your layout file:

<select onchange="location = this.value;">
  {% for ver in site.data.versions %}
    <option value="{{ ver.path }}" {% if page.url contains ver.version %}selected{% endif %}>{{ ver.version }}</option>
  {% endfor %}
</select>

Shared Layouts and Includes

Even though the content lives in separate folders per version, you can share the same layout and includes:

layouts/
├── doc.html
_includes/
├── toc.html

This keeps visual consistency across all versions.

Use Collections for More Control

If you prefer Jekyll collections over raw folders, define each version as a separate collection in _config.yml:

collections:
  v1_0:
    output: true
    permalink: /docs/v1.0/:path/
  v2_0:
    output: true
    permalink: /docs/v2.0/:path/

Then store content in _v1_0 and _v2_0 folders. This approach provides better metadata access and collection-wide iteration.

Version-specific TOC (Table of Contents)

Each version's TOC can be stored in _data/toc-v1_0.yml, _data/toc-v2_0.yml, and so on.

- title: "Getting Started"
  url: /docs/v1.0/index/
- title: "API"
  url: /docs/v1.0/api/

Search Integration per Version

To limit client-side search to the current version only, preload only the JSON index for that version. For example:

<script src="/docs/v2.0/search.json"></script>

This ensures search relevance and prevents results from older versions showing up unexpectedly.

Version Badging

Highlight the current version prominently using a badge:

<div class="version-badge">Version: {{ page.url | split: '/' | slice: 2,1 | first }}</div>

Versioning Guidelines for Authors

  • Copy from latest stable version when starting a new one.
  • Minimize duplication by using includes when content is identical.
  • Label breaking changes clearly across versions.

Managing Redirects Between Versions

In cases where pages have moved or renamed across versions, use Jekyll's jekyll-redirect-from plugin:

---
redirect_from: /docs/v1.0/old-feature/
permalink: /docs/v2.0/new-feature/
---

Benefits of Folder-Based Versioning

  • Straightforward organization and intuitive navigation.
  • Works well with static hosting like GitHub Pages.
  • Enables version-specific URLs for SEO and clarity.
  • Can be enhanced with version switchers and GitHub Actions.

Scaling Up: Automation and GitHub Actions

To automate the creation of a new version, use a script that:

  • Duplicates the latest version folder or collection.
  • Updates version number in all front matter.
  • Commits changes to GitHub for immediate deploy.

Conclusion

Building versioned documentation in Jekyll using folder-based routing is an elegant solution for maintaining scalable, user-friendly documentation. It requires a thoughtful structure but rewards you with clarity, maintainability, and complete control. Whether your product evolves monthly or yearly, this structure ensures your users are never left behind.

Next Ideas

  • Create version-aware breadcrumbs dynamically.
  • Build a diff tool to compare two versions of a document.
  • Implement version-based conditional rendering in templates.

Jekyll gives you the tools to scale your documentation—how you structure them is up to your creativity and discipline.