Improve documentation discovery with categorisation and filtering (#242)

tombentley · PaulRMellor · web-flow · commit f722a2e4f534 · 2026-03-29T21:13:53.000+01:00
* 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)

Added two new filter categories to better organise documentation:
- Security: for encryption, authentication, and authorisation guides
- Governance: for compliance and validation guides

Changes:
- Added 'security' tag to: Proxy guide, Record Encryption quickstart/guide,
  OAuth Bearer Validation, SASL Inspection, and Authorization guides
- Added 'governance' tag to: Record Validation Guide
- Removed overly-specific 'record-encryption' and 'encryption-at-rest' tags
- Added Security and Governance filter buttons with shield-lock and
  check-square-fill icons respectively
- Updated icon mapping and CSS border styles for new categories
- Applied changes to versions 0.16.0 through 0.19.0

Assisted-by: Claude Sonnet 4.5 &lt;noreply@anthropic.com&gt;
Co-authored-by: PaulRMellor &lt;47596553+PaulRMellor@users.noreply.github.com&gt;
Signed-off-by: Tom Bentley &lt;tbentley@redhat.com&gt;
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -20,3 +20,51 @@ Instead, issues for the website are held in the main Kroxylicious repo `https://
 So if you need to interact with website issues you can use the `-R kroxylicious/kroxylicious` option, for example: `gh issue list -R kroxylicious/kroxylicious`.
 
 When making commits, use the `Assisted-by:` trailer to attribute changes to AI tooling, rather than `Coauthored-by:`.
+
+## Documentation Filtering System
+
+The documentation index pages (`/documentation/` and `/documentation/{version}/`) use client-side filtering to help visitors find relevant guides.
+
+### Structure
+
+1. **Metadata**: Each version has a YAML file in `_data/documentation/` (e.g., `0_19_0.yaml`) containing guide metadata:
+   - `title`, `description`, `path`: Basic guide information
+   - `tags`: Array of category tags (e.g., `[filter, security]`)
+   - `rank`: String to control sort order (e.g., '000', '010')
+
+2. **Layout**: `_layouts/released-documentation.html` renders:
+   - Filter buttons (All, Proxy, Filters, Kubernetes, Developer, Security, Governance)
+   - Card grid with icons and tag badges
+   - Cards include a `data-categories` attribute for JavaScript filtering
+
+3. **Filtering**: `assets/scripts/doc-filter.js` provides vanilla JavaScript filtering
+   - Progressive enhancement: works without JavaScript
+   - Filters by matching tags in the `data-categories` attribute
+
+4. **Styling**: `_sass/kroxylicious.scss` provides:
+   - Filter button styles with active states
+   - Category-specific border colours on cards
+   - Icon and badge styling
+
+### Current Filter Categories
+
+- **proxy**: Core proxy functionality and configuration
+- **filter**: Filter plugins (encryption, validation, multi-tenancy, OAuth, SASL, authorization)
+- **kubernetes**: Kubernetes operator and deployment
+- **developer**: Development tools, guides, and API documentation
+- **security**: Security features (encryption, authentication, authorization)
+- **governance**: Compliance and validation
+
+### Adding New Categories
+
+To add a new filter category:
+
+1. Update YAML files in `_data/documentation/` for relevant versions
+2. Add filter button in `_layouts/released-documentation.html` with Bootstrap Icon
+3. Add icon mapping for card headers (same file)
+4. Add category border style in `_sass/kroxylicious.scss`
+5. No JavaScript changes needed (handles tags dynamically)
+
+### Version Scope Convention
+
+When updating documentation tags, typically update only recent versions (e.g., 0.16.0+) rather than all historical versions, to balance consistency with maintenance effort.
diff --git a/_data/documentation/0_16_0.yaml b/_data/documentation/0_16_0.yaml
@@ -9,14 +9,14 @@ docs:
     description: "Covers using the proxy, including configuration, security and operation."
     tags:
       - proxy
+      - security
     rank: '010'
     path: html/kroxylicious-proxy
   - title: Record Encryption quickstart
     description: Shows how to use the proxy to provide an encryption at rest solution
       for Apache Kafka
     tags:
-      - record-encryption
-      - encryption-at-rest
+      - security
     rank: '011'
     path: html/record-encryption-quickstart
   - title: Kroxylicious Operator for Kubernetes
@@ -31,12 +31,14 @@ docs:
       \ security and operation."
     tags:
       - filter
+      - security
     rank: '020'
     path: html/record-encryption-guide
   - title: Record Validation Guide
     description: Covers using the record validation filter.
     tags:
       - filter
+      - governance
     rank: '021'
     path: html/record-validation-guide
   - title: Multi-tenancy Guide
@@ -49,6 +51,7 @@ docs:
     description: Covers using the Oauth Bearer validation filter.
     tags:
       - filter
+      - security
     rank: '023'
     path: html/oauth-bearer-validation
   - title: Developer Quick Start
diff --git a/_data/documentation/0_17_0.yaml b/_data/documentation/0_17_0.yaml
@@ -9,14 +9,14 @@ docs:
     description: "Covers using the proxy, including configuration, security and operation."
     tags:
       - proxy
+      - security
     rank: '010'
     path: html/kroxylicious-proxy
   - title: Record Encryption quickstart
     description: Shows how to use the proxy to provide an encryption at rest solution
       for Apache Kafka
     tags:
-      - record-encryption
-      - encryption-at-rest
+      - security
     rank: '011'
     path: html/record-encryption-quickstart
   - title: Kroxylicious Operator for Kubernetes
@@ -31,12 +31,14 @@ docs:
       \ security and operation."
     tags:
       - filter
+      - security
     rank: '020'
     path: html/record-encryption-guide
   - title: Record Validation Guide
     description: Covers using the record validation filter.
     tags:
       - filter
+      - governance
     rank: '021'
     path: html/record-validation-guide
   - title: Multi-tenancy Guide
@@ -49,12 +51,14 @@ docs:
     description: Covers using the SASL Inspection filter.
     tags:
       - filter
+      - security
     rank: '023'
     path: html/sasl-inspection-guide
   - title: Oauth Bearer Validation Guide
     description: Covers using the Oauth Bearer validation filter.
     tags:
       - filter
+      - security
     rank: '023'
     path: html/oauth-bearer-validation
   - title: Developer Quick Start
diff --git a/_data/documentation/0_17_1.yaml b/_data/documentation/0_17_1.yaml
@@ -9,14 +9,14 @@ docs:
     description: "Covers using the proxy, including configuration, security and operation."
     tags:
       - proxy
+      - security
     rank: '010'
     path: html/kroxylicious-proxy
   - title: Record Encryption quickstart
     description: Shows how to use the proxy to provide an encryption at rest solution
       for Apache Kafka
     tags:
-      - record-encryption
-      - encryption-at-rest
+      - security
     rank: '011'
     path: html/record-encryption-quickstart
   - title: Kroxylicious Operator for Kubernetes
@@ -31,12 +31,14 @@ docs:
       \ security and operation."
     tags:
       - filter
+      - security
     rank: '020'
     path: html/record-encryption-guide
   - title: Record Validation Guide
     description: Covers using the record validation filter.
     tags:
       - filter
+      - governance
     rank: '021'
     path: html/record-validation-guide
   - title: Multi-tenancy Guide
@@ -49,12 +51,14 @@ docs:
     description: Covers using the SASL Inspection filter.
     tags:
       - filter
+      - security
     rank: '023'
     path: html/sasl-inspection-guide
   - title: Oauth Bearer Validation Guide
     description: Covers using the Oauth Bearer validation filter.
     tags:
       - filter
+      - security
     rank: '023'
     path: html/oauth-bearer-validation
   - title: Developer Quick Start
diff --git a/_data/documentation/0_18_0.yaml b/_data/documentation/0_18_0.yaml
@@ -9,14 +9,14 @@ docs:
     description: "Covers using the proxy, including configuration, security and operation."
     tags:
       - proxy
+      - security
     rank: '010'
     path: html/kroxylicious-proxy
   - title: Record Encryption quickstart
     description: Shows how to use the proxy to provide an encryption at rest solution
       for Apache Kafka
     tags:
-      - record-encryption
-      - encryption-at-rest
+      - security
     rank: '011'
     path: html/record-encryption-quickstart
   - title: Kroxylicious Operator for Kubernetes
@@ -31,12 +31,14 @@ docs:
       \ security and operation."
     tags:
       - filter
+      - security
     rank: '020'
     path: html/record-encryption-guide
   - title: Record Validation Guide
     description: Covers using the record validation filter.
     tags:
       - filter
+      - governance
     rank: '021'
     path: html/record-validation-guide
   - title: Multi-tenancy Guide
@@ -49,12 +51,14 @@ docs:
     description: Covers using the SASL Inspection filter.
     tags:
       - filter
+      - security
     rank: '023'
     path: html/sasl-inspection-guide
   - title: Oauth Bearer Validation Guide
     description: Covers using the Oauth Bearer validation filter.
     tags:
       - filter
+      - security
     rank: '023'
     path: html/oauth-bearer-validation
   - title: Developer Quick Start
diff --git a/_data/documentation/0_19_0.yaml b/_data/documentation/0_19_0.yaml
@@ -9,14 +9,14 @@ docs:
     description: "Covers using the proxy, including configuration, security and operation."
     tags:
       - proxy
+      - security
     rank: '010'
     path: html/kroxylicious-proxy
   - title: Record Encryption quickstart
     description: Shows how to use the proxy to provide an encryption at rest solution
       for Apache Kafka
     tags:
-      - record-encryption
-      - encryption-at-rest
+      - security
     rank: '011'
     path: html/record-encryption-quickstart
   - title: Kroxylicious Operator for Kubernetes
@@ -31,12 +31,14 @@ docs:
       \ security and operation."
     tags:
       - filter
+      - security
     rank: '020'
     path: html/record-encryption-guide
   - title: Record Validation Guide
     description: Covers using the record validation filter.
     tags:
       - filter
+      - governance
     rank: '021'
     path: html/record-validation-guide
   - title: Multi-tenancy Guide
@@ -49,18 +51,21 @@ docs:
     description: Covers using the Oauth Bearer validation filter.
     tags:
       - filter
+      - security
     rank: '023'
     path: html/oauth-bearer-validation
   - title: SASL Inspection Guide
     description: Covers using the SASL Inspection filter.
     tags:
       - filter
+      - security
     rank: '023'
     path: html/sasl-inspection-guide
   - title: Authorization Guide
     description: Covers using the Authorization filter.
     tags:
       - filter
+      - security
     rank: '024'
     path: html/authorization-guide
   - title: Developer Quick Start
diff --git a/_layouts/released-documentation.html b/_layouts/released-documentation.html
@@ -35,8 +35,32 @@ <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
+      </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>
+      <button class="btn btn-sm btn-outline-secondary" data-filter="security">
+        <i class="bi bi-shield-lock"></i> Security
+      </button>
+      <button class="btn btn-sm btn-outline-secondary" data-filter="governance">
+        <i class="bi bi-check-square-fill"></i> Governance
+      </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 +73,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 == 'security' %}shield-lock{% elsif primary_tag == 'governance' %}check-square-fill{% 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 +96,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>
diff --git a/_sass/kroxylicious.scss b/_sass/kroxylicious.scss
diff --git a/assets/scripts/doc-filter.js b/assets/scripts/doc-filter.js
