|
| 1 | +This is the repo for the website associated with Kroxylicious. |
| 2 | +Kroxylicious is a Layer 7 proxy for the Kafka protocol. |
| 3 | +The website uses Jekyll and is hosted on github. |
| 4 | + |
| 5 | +The content in this repo is a mixture of two things: |
| 6 | + |
| 7 | +* static markdown and HTML content, which doesn't change much between releases of the Kroxylicious software. |
| 8 | +* version-specific documentation, where a new release of the Kroxylicious software produces new documentation about that version. |
| 9 | + |
| 10 | +The version-specific content has index pages enumerating the downloads and documentation publications, which is templated using liquid templates. |
| 11 | + |
| 12 | +When you make a change you should test it. |
| 13 | +The script `./run.sh` can be used to serve the site from a docker container. |
| 14 | +The preview site can then be accessed at `http://127.0.0.1:4000/`. |
| 15 | + |
| 16 | +This GitHub repository is hosted on GitHub at `https://github.com/kroxylicious/kroxylicious.github.io`. |
| 17 | +You can use the `gh` tool to interact with GitHub PRs. |
| 18 | +Note that we do not use the website repo for issues. |
| 19 | +Instead, issues for the website are held in the main Kroxylicious repo `https://github.com/kroxylicious/kroxylicious`. |
| 20 | +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`. |
| 21 | + |
| 22 | +When making commits, use the `Assisted-by:` trailer to attribute changes to AI tooling, rather than `Coauthored-by:`. |
| 23 | + |
| 24 | +## Documentation Filtering System |
| 25 | + |
| 26 | +The documentation index pages (`/documentation/` and `/documentation/{version}/`) use client-side filtering to help visitors find relevant guides. |
| 27 | + |
| 28 | +### Structure |
| 29 | + |
| 30 | +1. **Metadata**: Each version has a YAML file in `_data/documentation/` (e.g., `0_19_0.yaml`) containing guide metadata: |
| 31 | + - `title`, `description`, `path`: Basic guide information |
| 32 | + - `tags`: Array of category tags (e.g., `[filter, security]`) |
| 33 | + - `rank`: String to control sort order (e.g., '000', '010') |
| 34 | + |
| 35 | +2. **Layout**: `_layouts/released-documentation.html` renders: |
| 36 | + - Filter buttons (All, Proxy, Filters, Kubernetes, Developer, Security, Governance) |
| 37 | + - Card grid with icons and tag badges |
| 38 | + - Cards include a `data-categories` attribute for JavaScript filtering |
| 39 | + |
| 40 | +3. **Filtering**: `assets/scripts/doc-filter.js` provides vanilla JavaScript filtering |
| 41 | + - Progressive enhancement: works without JavaScript |
| 42 | + - Filters by matching tags in the `data-categories` attribute |
| 43 | + |
| 44 | +4. **Styling**: `_sass/kroxylicious.scss` provides: |
| 45 | + - Filter button styles with active states |
| 46 | + - Category-specific border colours on cards |
| 47 | + - Icon and badge styling |
| 48 | + |
| 49 | +### Current Filter Categories |
| 50 | + |
| 51 | +- **proxy**: Core proxy functionality and configuration |
| 52 | +- **filter**: Filter plugins (encryption, validation, multi-tenancy, OAuth, SASL, authorization) |
| 53 | +- **kubernetes**: Kubernetes operator and deployment |
| 54 | +- **developer**: Development tools, guides, and API documentation |
| 55 | +- **security**: Security features (encryption, authentication, authorization) |
| 56 | +- **governance**: Compliance and validation |
| 57 | + |
| 58 | +### Adding New Categories |
| 59 | + |
| 60 | +To add a new filter category: |
| 61 | + |
| 62 | +1. Update YAML files in `_data/documentation/` for relevant versions |
| 63 | +2. Add filter button in `_layouts/released-documentation.html` with Bootstrap Icon |
| 64 | +3. Add icon mapping for card headers (same file) |
| 65 | +4. Add category border style in `_sass/kroxylicious.scss` |
| 66 | +5. No JavaScript changes needed (handles tags dynamically) |
| 67 | + |
| 68 | +### Version Scope Convention |
| 69 | + |
| 70 | +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. |
0 commit comments