handling version redirects in jekyll docs
Understanding Version Redirects in Documentation Sites
As your project evolves, older versions of documentation accumulate. To ensure users always see the most relevant content, you need a system that automatically redirects them to the latest stable version if no specific version is specified in the URL.
This approach prevents confusion and improves user experience, especially for beginners who may not understand version-specific paths.
Default Redirects to Latest Version
Assume your documentation is organized under versioned folders like /docs/v1.0/, /docs/v2.0/, and so on. When someone visits /docs/ without specifying a version, you want to redirect them to the latest version.
Step 1: Create a Redirect Page
Create a file at /docs/index.html with the following content:
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="refresh" content="0; url={{ '/docs/v2.0/' | relative_url }}" />
</head>
<body>
<p>Redirecting to latest documentation...</p>
</body>
</html>
Replace v2.0 with the actual latest version of your documentation. Each time you release a new version, update this file.
Step 2: Automate the Redirect (Optional)
If you're using data files or structured naming for versions, you could automate this using Liquid. First, define your versions in a data file like _data/versions.yml:
- v1.0
- v2.0
- v3.0
Then in /docs/index.html:
{% raw %}
---
layout: null
---
{% assign latest = site.data.versions | last %}
<meta http-equiv="refresh" content="0; url={{ '/docs/' | append: latest | append: '/' | relative_url }}" />
{% endraw %}
Creating a Version Switcher for Navigation
Help users quickly switch between versions by offering a dropdown or button-based version selector on every doc page.
Step 1: Include Version Info in Layout
Edit your documentation layout template (e.g. _layouts/doc.html) to include a version selector:
{% raw %}
<select id="versionSwitcher">
{% for ver in site.data.versions %}
<option value="{{ ver }}" {% if page.version == ver %}selected{% endif %}>{{ ver }}</option>
{% endfor %}
</select>
{% endraw %}
Step 2: Handle Version Switching in JavaScript
<script>
document.getElementById('versionSwitcher').addEventListener('change', function () {
const selectedVersion = this.value;
const path = window.location.pathname;
const newPath = path.replace(/\/docs\/v[\d\.]+\//, `/docs/${selectedVersion}/`);
window.location.href = newPath;
});
</script>
This script ensures that when a user selects another version, they are redirected to the equivalent page in that version—if it exists.
Maintaining Backward Compatibility
For older bookmarks or links pointing to unversioned paths, consider creating additional redirect pages using the same meta-refresh technique.
Alternatively, create symbolic redirects using GitHub Pages’ built-in static redirects via HTML files with JavaScript or meta tags, depending on your setup.
Communicate Version Differences
Consider showing a banner at the top of each page when users are browsing a version that’s outdated or not recommended. Example:
<div class="version-alert">
You are viewing version v1.0. <a href="/docs/v3.0/">Click here for the latest version.</a>
</div>
Conclusion
Redirects and version switching may seem like small enhancements, but they greatly improve the usability of multi-version documentation. New users land on the latest stable content, while advanced users can easily reference older versions when needed.
In the next guide, we’ll explore how to create version-specific search indexes so users don’t see outdated results when using client-side search tools.
