Improve documentation discovery with visual categorisation and filtering

Added icons, badges, and client-side filtering to documentation index pages
to help visitors quickly find relevant guides as the guide count grows.

- Filter buttons (All, Proxy, Filters, Kubernetes, Developer) with counts
- Category icons in card headers using Bootstrap Icons (cpu, puzzle, boxes, code-slash, shield-lock)
- Visible tag badges at bottom of cards
- Subtle category-specific border colours on cards
- Vanilla JavaScript for client-side filtering with progressive enhancement
- Cards reflow properly when filtered (no gaps in grid layout)

Assisted-by: Claude Sonnet 4.5 <noreply@anthropic.com>
Signed-off-by: Tom Bentley <tbentley@redhat.com>

Author: tombentley

_layouts/released-documentation.html

@@ -35,8 +35,26 @@ <h1 id="page-title" class="fs-3">{{ version }} Documentation</h1>
     </div>
   </div>
   <div class="col-lg-6" role="main">
-    <div class="row row-cols-1 row-cols-md-2 g-4">
 {%- assign docs_for_release = site.data.documentation[underscored_version].docs | sort: "rank" -%}
+    <!-- Documentation filters -->
+    <div class="doc-filters mb-4" role="toolbar" aria-label="Documentation filters">
+      <button class="btn btn-sm btn-outline-secondary active" data-filter="all">
+        All <span class="badge">{{ docs_for_release | size }}</span>
+      </button>
+      <button class="btn btn-sm btn-outline-secondary" data-filter="proxy">
+        <i class="bi bi-cpu"></i> Proxy
+      </button>
+      <button class="btn btn-sm btn-outline-secondary" data-filter="filter">
+        <i class="bi bi-puzzle"></i> Filters
+      </button>
+      <button class="btn btn-sm btn-outline-secondary" data-filter="kubernetes">
+        <i class="bi bi-boxes"></i> Kubernetes
+      </button>
+      <button class="btn btn-sm btn-outline-secondary" data-filter="developer">
+        <i class="bi bi-code-slash"></i> Developer
+      </button>
+    </div>
+    <div class="row row-cols-1 row-cols-md-2 g-4">
 {%- for doc in docs_for_release -%}
 {%- assign first1 = doc.path | slice: 0, 1 -%}
 {%- assign first7 = doc.path | slice: 0, 7 -%}
@@ -49,12 +67,21 @@ <h1 id="page-title" class="fs-3">{{ version }} Documentation</h1>
 {%- assign linkTemplate = "/documentation/" | append: version | append: "/" | append: doc.path | absolute_url -%}
 {%- endif -%}
       <div class="col">
-        <div class="card shadow mb-2 h-100 mx-2 {%- for tag in doc.tags %} doctag-{{tag}}{%- endfor -%}">
-          <div class="card-header">
-            <h2 class="card-title fs-4"><a href='{{ linkTemplate | replace: "$(VERSION)", version}}'>{{ doc.title }}</a></h2>
+        <div class="card shadow mb-2 h-100 mx-2 doc-card{%- for tag in doc.tags %} doctag-{{tag}}{%- endfor -%}" data-categories="{{ doc.tags | join: ' ' }}">
+          <div class="card-header d-flex align-items-center justify-content-between">
+            <h2 class="card-title fs-4 mb-0 flex-grow-1">
+              <a href='{{ linkTemplate | replace: "$(VERSION)", version}}'>{{ doc.title }}</a>
+            </h2>
+{%- assign primary_tag = doc.tags[0] -%}
+            <i class="bi bi-{% if primary_tag == 'proxy' %}cpu{% elsif primary_tag == 'filter' %}puzzle{% elsif primary_tag == 'kubernetes' %}boxes{% elsif primary_tag == 'developer' %}code-slash{% elsif primary_tag == 'record-encryption' or primary_tag == 'encryption-at-rest' %}shield-lock{% else %}file-text{% endif %} text-secondary ms-2" aria-hidden="true"></i>
           </div>
           <div class="card-body mx-3 my-2">
 {{ doc.description }}
+            <div class="mt-2">
+{%- for tag in doc.tags -%}
+              <span class="badge bg-light text-dark border me-1">{{ tag }}</span>
+{%- endfor -%}
+            </div>
           </div>
         </div>
       </div>
@@ -63,3 +90,4 @@ <h2 class="card-title fs-4"><a href='{{ linkTemplate | replace: "$(VERSION)", ve
   </div>
 </div>
 
+<script src="{{ '/assets/scripts/doc-filter.js' | absolute_url }}"></script>

_sass/kroxylicious.scss

@@ -354,3 +354,79 @@ b.conum * {
   margin-top: calc(var(--#{$prefix}card-title-spacer-y) / 2);
   margin-bottom: calc(var(--#{$prefix}card-title-spacer-y) / 2);
 }
+
+// Documentation page filtering
+.doc-filters {
+  display: flex;
+  gap: 0.5rem;
+  flex-wrap: wrap;
+  padding: 1rem;
+  background-color: rgba($kroxy-light, 0.3);
+  border-radius: 0.375rem;
+
+  .btn {
+    transition: all 0.2s ease-in-out;
+
+    &.active {
+      background-color: $kroxy-dark-green;
+      color: $white;
+      border-color: $kroxy-dark-green;
+    }
+
+    &:hover:not(.active) {
+      background-color: rgba($kroxy-light-green, 0.1);
+    }
+
+    .bi {
+      font-size: 0.9rem;
+    }
+
+    .badge {
+      background-color: rgba($white, 0.3);
+      color: currentColor;
+      font-weight: normal;
+      margin-left: 0.25rem;
+    }
+  }
+}
+
+.col.hidden {
+  display: none;
+}
+
+.doc-card {
+  transition: opacity 0.3s ease-in-out, transform 0.3s ease-in-out;
+
+  .card-header {
+    border-bottom: 3px solid transparent;
+  }
+
+  // Visual category hints
+  &.doctag-proxy .card-header {
+    border-bottom-color: rgba($kroxy-light-green, 0.3);
+  }
+
+  &.doctag-filter .card-header {
+    border-bottom-color: rgba($kroxy-mid-green, 0.3);
+  }
+
+  &.doctag-kubernetes .card-header {
+    border-bottom-color: rgba($kroxy-dark-green, 0.3);
+  }
+
+  &.doctag-developer .card-header {
+    border-bottom-color: rgba($code-color, 0.3);
+  }
+
+  .badge {
+    font-size: 0.7rem;
+    padding: 0.25rem 0.5rem;
+    text-transform: lowercase;
+  }
+
+  // Icon in card header
+  .card-header .bi {
+    font-size: 1.5rem;
+    opacity: 0.4;
+  }
+}

assets/scripts/doc-filter.js

@@ -0,0 +1,65 @@
+/**
+ * Documentation page filter functionality
+ * Provides client-side filtering of documentation cards by category
+ */
+(function() {
+  'use strict';
+
+  // Wait for DOM to be ready
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', init);
+  } else {
+    init();
+  }
+
+  function init() {
+    const filters = document.querySelectorAll('.doc-filters button[data-filter]');
+    const cards = document.querySelectorAll('.doc-card');
+
+    if (filters.length === 0 || cards.length === 0) {
+      return; // Not on a documentation page
+    }
+
+    filters.forEach(button => {
+      button.addEventListener('click', function() {
+        const filter = this.getAttribute('data-filter');
+        applyFilter(filter, filters, cards);
+      });
+    });
+  }
+
+  function applyFilter(filter, filterButtons, cards) {
+    // Update active button
+    filterButtons.forEach(btn => {
+      if (btn.getAttribute('data-filter') === filter) {
+        btn.classList.add('active');
+      } else {
+        btn.classList.remove('active');
+      }
+    });
+
+    // Filter cards
+    let visibleCount = 0;
+    cards.forEach(card => {
+      const categories = card.getAttribute('data-categories') || '';
+      const shouldShow = filter === 'all' || categories.includes(filter);
+      const colWrapper = card.closest('.col');
+
+      if (shouldShow) {
+        if (colWrapper) colWrapper.classList.remove('hidden');
+        visibleCount++;
+      } else {
+        if (colWrapper) colWrapper.classList.add('hidden');
+      }
+    });
+
+    // Update badge count on "All" button
+    const allButton = document.querySelector('.doc-filters button[data-filter="all"]');
+    if (allButton) {
+      const badge = allButton.querySelector('.badge');
+      if (badge && filter !== 'all') {
+        badge.textContent = visibleCount;
+      }
+    }
+  }
+})();