Versioning system for Jekyll

error404.html

---
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>

Jekyll Version Switcher

See README.adoc

license

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.adoc

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.

version-switcher.html

{% 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>

version-switcher.js

/* requires jQuery */
$(function(){
  $('select#versions').on('change', function () {
    var url = $(this).val();
    if (url) {
      window.location = url;
      $.cookie('version', $(this).val());
    }
    return false;
  });
});

versioner.liquid

{%- 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 %}

versions.yml

# 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

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?