Skip to content

Instantly share code, notes, and snippets.

@briandominick
Last active March 3, 2022 05:29
  • Star 0 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
Star You must be signed in to star a gist
Save briandominick/9ee17e4350f56e50a6fc0cf570e61c8c to your computer and use it in GitHub Desktop.
Versioning system for Jekyll
---
layout: default
---
{% include versioner.liquid %}
<div class="home">
<p><b>Sorry; the page you requested was not found.</b></p>
<script>
var url = document.URL;
if (url.includes("/v")) {
var re = /(v[4-9]\-[0-9]{1,2})[\.html|\/]/;
var v = re.exec(url);
var vsn = v[1];
var vrsn = vsn.replace("-",".").replace("v","");
if (vrsn < 5.4) {
var install_only = true;
}
if (install_only) {
var path = "/" + vsn + "/install-guide/";
} else {
if ( vrsn == {{latest.id}} ) {
var vsni = "";
} else {
var vsni = "-" + vsn;
}
var path = "/index" + vsni + ".html";
}
document.write('<p>You were looking for a versioned page that does not exist in version ' + vrsn + '. <strong>Try the <a href="' + path + '">version homepage</a></strong>.</p>');
}
</script>
{% assign versions = site.data.versions | reverse %}
{% assign latest = versions | where: "latest", "true" %}
<h2>Version Homepages</h2>
<ul>
{% for v in versions %}
{% assign path = "" %}
{% if v.full %}
{% capture path %}/index-{{v.slug}}.html{% endcapture %}
{% if v.slug == latest[0].slug %}
{% assign path = "/" %}
{% endif %}
{% else %}
{% capture path %}/{{v.slug}}/install-guide/{% endcapture %}
{% endif %}
<li><a href="{{path}}">Version {{ v.id }}</a></li>
{% endfor %}
</ul>
</div>
Copyright 2019 Pepperdata, Inc
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation
files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy,
modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software
is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR
IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Version Switcher

Just a quick release of files written when Codewriting, LLC added version switching to Pepperdata’s Jekyll-based docs site. More documentation may be added after release approval, but for now this code is as-is.

License

Released jointly under the MIT Licence.

{% include versioner.liquid %}
{% comment %}
Generates a version switcher that is context aware of its version, using the
current page's version as the default selected option.
{% endcomment %}
<div class="version-switcher {{ layout.display }}">
<form>
<label class="select">Product Version
<select id="versions" name="version">
{%- for v in site.data.versions -%}
{%- assign selected = "" -%}
{%- if page_version == v.slug -%}
{%- assign selected = "selected" -%}
{%- endif -%}
{%- if page_type == "latest-index" -%}
{%- capture path -%}index-{{ v.slug }}.html{%- endcapture -%}
{%- else -%}
{%- assign path = page.url | replace: page_version, v.slug -%}
{%- endif -%}
{%- if v.full -%}
{%- if page_type == "old-index" and v.slug == latest.slug -%}
{%- assign path = "/" -%}
{%- endif %}
<option value="{{ path }}" {{ selected }}>{{ v.id }}</option>
{%- else -%}
{%- if path_split[1] == "install-guide" %}
<option value="{{ path }}" {{ selected }}>{{ v.id }}</option>
{%- endif -%}
{%- endif -%}
{%- endfor %}
</select>
</label>
</form>
</div>
/* requires jQuery */
$(function(){
$('select#versions').on('change', function () {
var url = $(this).val();
if (url) {
window.location = url;
$.cookie('version', $(this).val());
}
return false;
});
});
{%- comment -%}
Uses _data/versions.yml to scope out version history, conditionally
preparing each expected version path, depending on whether it's a current
index, old index, or a versioned non-index page.
Display can be disabled using `versioning: false` in a page's frontmatter.
{%- endcomment -%}
{%- assign latest_qry = site.data.versions | where: "latest", "true" -%}
{%- assign latest = latest_qry[0] -%}
{%- assign name_strip = page.name | remove: ".html" -%}
{%- assign name_split = name_strip | split: "-" -%}
{%- assign path_split = page.path | split: "/" -%}
{%- if page.url == "/" -%}{%- comment -%}site homepage{% endcomment %}
{%- assign page_type = "latest-index" -%}
{%- assign page_version = latest.slug -%}
{%- else -%}
{%- if name_split[0] == "index" -%}{%- comment -%}older index{% endcomment %}
{%- assign page_type = "old-index" -%}
{%- capture page_version -%}{{name_split[1]}}-{{name_split[2]}}{%- endcapture -%}
{%- else -%}
{%- if page.collection -%}
{%- assign col = site.collections | where: "label", page.collection -%}
{%- if col[0].type == "version" -%}
{%- comment -%}A page in a versioned collection{% endcomment %}
{%- assign page_type = "versioned" -%}
{%- assign page_version = page.collection -%}
{%- else -%}
{%- assign page_type = "unversioned" -%}
{%- endif -%}
{%- else -%}
{%- assign page_type = "unversioned" -%}
{%- assign page_version = latest.slug -%}
{%- endif -%}
{%- endif -%}
{%- endif %}
{% assign page_vsn_qry = site.data.versions | where: "slug", page_version %}
{% assign page_vsn_obj = page_vsn_qry[0] | default: latest %}
# Expressions of supported product versions
# Settings
# label: the text to express in homepage links to the docs.
- float: 5.0
id: "5.0"
slug: v5-0
label: "5.0"
- float: 5.1
id: "5.1"
slug: v5-1
label: "5.1"
- float: 5.2
id: "5.2"
slug: v5-2
label: "5.2"
- float: 5.3
id: "5.3"
slug: v5-3
label: "5.3"
- float: 5.4
id: "5.4"
slug: v5-4
label: "5.4"
latest:
- float: 5.5
id: "5.5"
slug: v5-5dev
label: 5.5dev
@charlespepper
Copy link

Pepperdata, Inc approves this matter for release as-is, without warranty, under The MIT License.

@Daeruin
Copy link

Daeruin commented Mar 3, 2022

I would love to see a quick explanation of how these files work together and how to get a minimum version switcher working. How do you identify a given page as belonging to a specific version? Put something in the front matter, put the file in a collection, or what? Are there naming conventions or an expected folder structure?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment