feat: Add configurable redirects.

SamBarker · web-flow · commit 75bfac389e31 · 2025-07-16T08:47:40.000+01:00
Generate redirects
diff --git a/.gitignore b/.gitignore
@@ -7,3 +7,4 @@ vendor
 *.iml
 */bootstrap/
 _config-overrides.yml
+.ruby-version
diff --git a/Gemfile.lock b/Gemfile.lock
@@ -22,8 +22,12 @@ GEM
       eventmachine (>= 0.12.9)
       http_parser.rb (~> 0)
     eventmachine (1.2.7)
+    ffi (1.17.2-arm64-darwin)
     ffi (1.17.2-x86_64-linux-gnu)
     forwardable-extended (2.6.0)
+    google-protobuf (4.31.1-arm64-darwin)
+      bigdecimal
+      rake (>= 13)
     google-protobuf (4.31.1-x86_64-linux-gnu)
       bigdecimal
       rake (>= 13)
@@ -73,6 +77,8 @@ GEM
       rb-fsevent (~> 0.10, >= 0.10.3)
       rb-inotify (~> 0.9, >= 0.9.10)
     mercenary (0.4.0)
+    nokogiri (1.18.8-arm64-darwin)
+      racc (~> 1.4)
     nokogiri (1.18.8-x86_64-linux-gnu)
       racc (~> 1.4)
     pathutil (0.16.2)
@@ -86,6 +92,8 @@ GEM
     rexml (3.4.1)
     rouge (4.5.2)
     safe_yaml (1.0.5)
+    sass-embedded (1.89.2-arm64-darwin)
+      google-protobuf (~> 4.31)
     sass-embedded (1.89.2-x86_64-linux-gnu)
       google-protobuf (~> 4.31)
     terminal-table (3.0.2)
@@ -94,6 +102,7 @@ GEM
     webrick (1.9.1)
 
 PLATFORMS
+  arm64-darwin-24
   x86_64-linux
 
 DEPENDENCIES
diff --git a/README.md b/README.md
@@ -60,3 +60,16 @@ should go under `/assets/`. To try and preserve a bit of sanity to the repo we s
 Some content such as the use-cases include diagrams drawn in Excalidraw.  Browsers can't handle the format natively, so instead, in addition to
 commiting the `.excalidraw` orginals to the repo, we also export a transparent `.png` for inclusion in the content.
 
+# Redirects
+There is nothing more frustrating than reading some documentation or a stack trace with a link to some helpful sounding answer only for that link to be a 404. To try and minimise that pain we have built a Jekyll plugin to generate a redirect from a token to a URL. This plug-in generates a collection of static pages derived from the yaml documents in `_data/redirects`.
+Each yaml document defines a namespace for redirections. For example `errors.yaml` will build pages under `/redirects/errors/`. The yaml document takes the format outlined here:
+
+```yaml
+baseUrl: https://kroxylicious.io/documentation/ #The base URL to build redirects from
+delay: 3 #How long should the re-direction message be shown before loading the target. Defaults to 1.
+mappings:
+- name: test #the token to be the landing url
+  fromVersion: 0.10.0 #Optional, if not specified the latest release at time of site build is used. 
+  toVersion: 0.12.0 #Optional, if not specified the latest release at time of site build  is used.
+  path: /html/kroxylicious-proxy/#con-configuring-client-connections-proxy # the path within the baseUrl
+```
diff --git a/_config.yml b/_config.yml
@@ -83,3 +83,10 @@ asciidoctor:
     toc: preamble
     source-highlighter: rouge
     sectanchors: ''
+
+defaults:
+  - scope:
+      type: pages
+      path: /redirects
+    values:
+      layout: redirect.html
diff --git a/_data/redirects/errors.yaml b/_data/redirects/errors.yaml
@@ -0,0 +1,9 @@
+baseUrl: https://kroxylicious.io/documentation/
+delay: 3
+mappings:
+  - name: clientTls
+    fromVersion: 0.13.0
+    path: /html/kroxylicious-proxy/#con-configuring-client-connections-proxy
+
+
+
diff --git a/_layouts/redirect.html b/_layouts/redirect.html
@@ -0,0 +1,30 @@
+<!doctype html>
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>{% if page.title %}{{ page.title }} | {% endif %}{{ site.title }} | {{ site.description }}</title>
+    <link rel="icon" href="{{ '/favicon.ico' | absolute_url }}" type="image/x-icon"/>
+    <link rel="stylesheet" href="{{ '/css/style.css' | absolute_url }}"/>
+    <link rel="stylesheet"
+          href="https://cdnjs.cloudflare.com/ajax/libs/bootstrap-icons/1.11.1/font/bootstrap-icons.min.css"
+          integrity="sha512-oAvZuuYVzkcTc2dH5z1ZJup5OmSQ000qlfRvuoTTiyTBjwX1faoyearj8KdMq0LgsBTHMrRuMek7s+CxF8yE+w=="
+          crossorigin="anonymous" referrerpolicy="no-referrer"/>
+    <script src="https://cdnjs.cloudflare.com/ajax/libs/bootstrap/5.3.2/js/bootstrap.bundle.min.js"
+            integrity="sha512-X/YkDZyjTf4wyc2Vy16YGCPHwAY8rZJY+POgokZjQB2mhIRFJCckEGc6YyX9eNsPfn0PzThEuNs+uaomE5CO6A=="
+            crossorigin="anonymous" referrerpolicy="no-referrer"></script>
+    <meta http-equiv="refresh" content="{{ page.delay }}; url={{ page.target }}">
+</head>
+<body class="d-flex flex-column min-vh-100" data-bs-theme="light">
+{% include nav.html %}
+<div class="container-fluid px-0 krx-content" data-bs-theme="light">
+    <div class="paragraph" role="main">
+        <div>Redirecting to <a href="{{ page.target }}">{{ page.target }}</a>...</div>
+        <div class="spinner-border text-success" role="status">
+            <span class="visually-hidden">waiting...</span>
+        </div>
+    </div>
+</div>
+{% include footer.html %}
+</body>
+<body>
diff --git a/_plugins/redirector.rb b/_plugins/redirector.rb
@@ -0,0 +1,135 @@
+module SamplePlugin
+  class RedirectPageGenerator < Jekyll::Generator
+    safe true
+
+    def generate(site)
+      config = site.data['redirects']
+      latest_release = Version.parse(site.data['kroxylicious']['latestRelease'])
+      releases = known_releases(site)
+      config.each { |redirect_config|
+        Jekyll.logger.info "generating redirects for #{redirect_config[0]}"
+        redirect_config[1]['mappings'].each do |mapping|
+          to_version = Version.parse(mapping['toVersion'] ||= latest_release)
+          from_version = Version.parse(mapping['fromVersion'] ||= latest_release)
+          versions = releases.select { |rel| rel.between?(from_version, to_version) }
+          versions.each { |version|
+            mapping['version'] = version
+            site.pages << RedirectPage.new(site, redirect_config[0], redirect_config[1], mapping)
+          }
+        end
+        Jekyll.logger.info "Generated redirects #{redirect_config[0]}"
+      }
+    end
+
+    private
+
+    def known_releases(site)
+      releases = []
+      site.data['release'].sort.each do |release|
+        releases << Version.parse(release[0])
+      end
+      releases.sort_by { |version| [version.major, version.minor, version.patch] }
+    end
+  end
+
+  # Subclass of `Jekyll::Page` with custom method definitions.
+  class RedirectPage < Jekyll::Page
+    def initialize(site, group, redirectConfig, mapping)
+
+      @site = site # the current site instance.
+      @base = site.source # path to the source directory.
+      @dir = "/redirect/#{group}/#{mapping['version']}/" # the directory the page will reside in.
+
+      # All pages have the same filename, so define attributes straight away.
+      @basename = mapping['name'] # filename without the extension.
+      @ext = '.html' # the extension.
+      @name = basename + ext # basically @basename + @ext.
+      @layout = 'redirect.html'
+      delay = redirectConfig['delay'] ||= 1
+      @data = {
+        'target' => "#{redirectConfig['baseUrl']}#{mapping['version']}#{mapping['path']}",
+        'layout' => 'redirect',
+        'delay' => "#{delay}",
+      }
+
+      Jekyll.logger.info "generated redirect from #{@dir}#{@basename} to #{data['target']}"
+    end
+
+    # Placeholders that are used in constructing page URL.
+    def url_placeholders
+      {
+        :path => @dir,
+        :category => @dir,
+        :basename => basename,
+        :output_ext => output_ext,
+      }
+    end
+  end
+
+  class Version
+    include Comparable
+
+    # @return [Integer]
+    attr_reader :major
+
+    # @return [Integer]
+    attr_reader :minor
+
+    # @return [Integer]
+    attr_reader :patch
+
+    def self.parse(version_string)
+      if version_string.is_a? Version
+        return version_string
+      end
+      if version_string.include? '_'
+        parts = version_string.split('_').map { |x| x.to_i }
+      elsif version_string.include? '.'
+        parts = version_string.split('.').map { |x| x.to_i }
+      else
+        raise "Invalid version string: #{version_string}"
+      end
+      instance = allocate
+      instance.send(:initialize, parts[0], parts[1], parts[2])
+      instance
+    end
+
+    # @param [Integer] major
+    # @param [Integer] minor
+    # @param [Integer] patch
+    def initialize(
+      major,
+      minor,
+      patch
+    )
+      @major = major.to_i
+      @minor = minor.to_i
+      @patch = patch.to_i
+    end
+
+    # @return [String]
+    def to_s
+      "#{major}.#{minor}.#{patch}"
+    end
+
+    def ==(other)
+      to_s == other.to_s
+    end
+
+    # See section #11 of https://semver.org/spec/v2.0.0.html
+    # @return [Integer, nil] Returns -1, 0, or 1. or Nil if other is unsortable
+    def <=>(other)
+      if other.is_a? Version
+        [major, minor, patch] <=> [other.major, other.minor, other.patch]
+      else
+        nil
+      end
+    end
+
+    def between?(min, max)
+      if (min.is_a? Version) && (max.is_a? Version)
+        self >= min && self <= max
+      end
+    end
+  end
+end
