manage multiple doc versions with jekyll collections

Posted by -

Why Versioning Your Documentation Matters

As your project evolves, users may rely on different versions of your documentation. Keeping all versions accessible helps users find instructions that match their setup or software release, avoiding confusion.

Jekyll’s collection system can be adapted to manage multiple doc versions elegantly without complex tooling.

Step 1: Plan Your Version Structure

Decide how many versions you want to maintain (e.g., v1.0, v2.0, etc.) and how URLs will reflect versions. A common approach is:

  • /docs/v1.0/
  • /docs/v2.0/

This keeps URLs clean and intuitive.

Step 2: Setup Collections with Version Folders

In _config.yml, define a single docs collection:

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

Each doc markdown file inside _docs/ will have front matter specifying its version:

---
title: "Getting Started"
version: "v1.0"
permalink: /docs/v1.0/getting-started/
---

Step 3: Organize Files by Version

Inside _docs/, you can organize files in subfolders named after versions or keep all files flat but differentiated by front matter.

  • _docs/v1.0/getting-started.md
  • _docs/v2.0/getting-started.md

Or:

  • _docs/getting-started-v1.0.md
  • _docs/getting-started-v2.0.md

Step 4: Filter Docs by Version in Templates

Use Liquid to display docs filtered by version on version-specific landing pages:

{% raw %}

Documentation for Version {{ page.version }}



    
  {% assign filtered_docs = site.docs | where: "version", page.version %}
  {% for doc in filtered_docs %}
    
  • {{ doc.title }}
    • 
  {% endfor %}


{% endraw %}

Step 5: Create a Version Switcher UI

Help users jump between versions by adding a simple dropdown or menu:

{% raw %}

{% endraw %}

Enhance with JavaScript to auto-select the current version.

Step 6: Maintain Backward Compatibility

Keep older versions intact for users who haven’t upgraded. Avoid removing docs but mark deprecated versions clearly.

Step 7: Automate URL Generation

Using the permalink in front matter ensures URLs are consistent. Example:

---
title: "API Reference"
version: "v2.0"
permalink: /docs/v2.0/api-reference/
---

Step 8: Enhance Search Across Versions

When building your client-side search index, include the version field. This allows filtering or displaying version-specific results for users.

Conclusion

Managing multiple documentation versions in Jekyll is straightforward with collections and version metadata. This approach keeps your site organized and user-friendly, essential for professional projects or open-source libraries.

Next, we’ll explore how to add interactive client-side search for versioned docs to make navigation even smoother.