Rebuild the Clients page and add an Integrations page

.github/PULL_REQUEST_TEMPLATE/add_library.md

@@ -0,0 +1,133 @@
+<!-- Thanks for contributing to valkey.io! Everything you need is in this template. -->
+
+### What are you adding?
+
+<!-- Name of the client, tool, or integration, and a one-line summary. -->
+
+- [ ] Client library → `_data/libraries/clients/`
+- [ ] Integration (tool, framework, or AI/agent library) → `_data/libraries/integrations/`
+
+### Entry details
+
+- **Name:**
+- **Repository:**
+- **License (SPDX):**
+
+---
+
+## How entries work
+
+Each entry is a single flat JSON file under `_data/libraries/`, in one of two
+group directories, and registered by path in `_data/libraries/manifest.json`:
+
+- Client libraries → `_data/libraries/clients/` (appear on the **Clients** page)
+- Integrations → `_data/libraries/integrations/` (appear on the **Integrations** page)
+
+The directory decides which page shows the entry and which fields it needs.
+Integrations are the tools, frameworks, and AI libraries that work with Valkey:
+
+- Tools and frameworks: CLI and GUI apps, deployment and operations tooling,
+  proxies and gateways, frameworks and ORMs, queues and background jobs,
+  data-movement connectors, and observability or testing tools.
+- AI and agent libraries: AI memory platforms, agent frameworks, vector stores,
+  RAG and retrieval, and inference or serving engines.
+
+Name the file after your entry, lowercase and hyphenated (e.g.
+`valkey-glide-python.json`).
+CI checks every entry with `build/validate-libraries.py`, against
+`_data/libraries/schema.json`, the manifest, and the SPDX license list. To run
+the check locally, use `./build/validate-libraries.py` with
+[uv](https://docs.astral.sh/uv/) installed. The README's "Checking catalog
+entries" section shows how to run it without uv. No other repositories are
+needed.
+
+## Fields
+
+Entries are flat JSON objects, apart from a client's `features`. Use only the
+fields below.
+
+**Required for all entries:**
+
+- `name` (string) — official name.
+- `description` (string) — one or two factual, vendor-neutral sentences. The maximum length is set in `_data/libraries/schema.json`.
+- `license` (string) — SPDX identifier, e.g. `"Apache-2.0"`, `"MIT"`, `"BSD-3-Clause"`. Must be an OSI-approved open-source license.
+- `repository` (string) — public source-code repository URL. Entries whose repository is under `https://github.com/valkey-io/` are shown as maintained by Valkey.
+- `documentation` (string) — a link to a page that shows how to use the project with Valkey. For a page on valkey.io, use a root-relative path such as `/topics/cli/`; for any other site, an `https://` URL. Link the first of these that exists: a Valkey page in the project's docs, a Valkey example, a getting-started guide, or the README section that shows basic usage. For a library that speaks the Redis protocol, a page that shows the connection setup is enough. A homepage, a docs index, or a directory listing isn't. Link GitHub files at a tag or commit (`/blob/v1.2.3/…`), not a branch.
+
+**Required for clients:**
+
+- `language` (string) — primary language. Integrations that are imported into code, such as ORM adapters, SDK wrappers and agent frameworks, set it too. Standalone tools leave it out. If a library has a separate package for each language, add one entry per language. The allowed languages are in `_data/libraries/schema.json`. If yours isn't there, add it to the schema in your PR.
+- `features` (object of true/false flags) — one flag for each feature key listed under `features` in `_data/libraries/schema.json`. Set a flag to `true` if the client supports the feature, otherwise `false`. Include them all.
+
+The client example below shows the format.
+The label and definition of each feature, as shown on the site, are in `featureDescriptions` in `_data/libraries/metadata.json`.
+A feature that every listed client supports, or that none does, isn't shown on cards or in the legend, because it doesn't tell clients apart.
+So a feature you set can appear or disappear as other clients are added or removed.
+
+**Optional fields:**
+
+- `tags` (array of strings) — category tags that integrations use for filtering and discovery. Client entries have no tags. The allowed tags are in `_data/libraries/schema.json`. Use one of those where it fits. If none does, propose a new tag by adding it to the schema in your PR.
+- `installCommand` (string) — primary install command, e.g. `"pip install valkey-glide"`.
+
+## Example entries
+
+Client (`_data/libraries/clients/valkey-glide-python.json`):
+
+```json
+{
+  "name": "Valkey GLIDE Python",
+  "language": "Python",
+  "license": "Apache-2.0",
+  "description": "Designed for reliability, optimized performance, and high-availability. GLIDE is a multi-language client with one shared Rust core and per-language bindings.",
+  "repository": "https://github.com/valkey-io/valkey-glide/tree/main/python",
+  "documentation": "https://glide.valkey.io/getting-started/quickstart/?lang=python",
+  "installCommand": "pip install valkey-glide",
+  "features": {
+    "replica": true,
+    "backoff": true,
+    "pubsub": true,
+    "scan": true,
+    "latency": false,
+    "az": true,
+    "csc": false,
+    "capa": false,
+    "pool": false
+  }
+}
+```
+
+Integration (`_data/libraries/integrations/valkey-cli.json`):
+
+```json
+{
+  "name": "valkey-cli",
+  "language": "C",
+  "license": "BSD-3-Clause",
+  "description": "The interactive terminal client shipped with valkey-server, with cluster-aware routing, --scan, --bigkeys and latency diagnostics built in.",
+  "repository": "https://github.com/valkey-io/valkey",
+  "documentation": "/topics/cli/",
+  "tags": ["CLI & GUI"]
+}
+```
+
+## Register in the manifest
+
+Add the file's path (relative to `_data/libraries/`) to the matching array in
+`_data/libraries/manifest.json` — `clients` or `integrations`. List it exactly
+once; the page sorts cards by name, so the position doesn't matter. A file not
+in the manifest will not appear on the site.
+
+---
+
+### Submission checklist
+
+- [ ] Valid JSON, placed in `clients/` or `integrations/`, and registered once in `_data/libraries/manifest.json`.
+- [ ] All required fields present: `name`, `description`, `license`, `repository`, `documentation` — plus `language` and `features` for clients, with every flag.
+- [ ] Tested compatible with Valkey 7.2 or above.
+- [ ] OSI-approved open-source license.
+- [ ] Repository is publicly accessible, active within the last 6 months, and has a README with basic usage.
+- [ ] `documentation` opens on a page that shows how to use the project with Valkey, not a homepage or an index.
+- [ ] Description is factual, vendor-neutral and within the length limit in `_data/libraries/schema.json`. Every `features` flag and compatibility claim is accurate.
+- [ ] Commits are signed per the DCO using `--signoff`.
+
+By submitting this pull request, I confirm that my contribution is made under the terms of the BSD-3-Clause License.

.github/workflows/validate-libraries.yml

@@ -0,0 +1,37 @@
+name: Validate library catalog
+
+on:
+  pull_request:
+    branches: ["main"]
+    paths:
+      - '_data/libraries/**'
+      - 'build/validate-libraries.py'
+      - '.github/workflows/validate-libraries.yml'
+  workflow_call:
+    inputs:
+      ref:
+        description: The Git ref to validate. Leave it empty to validate the commit that triggered the run.
+        type: string
+        required: false
+        default: ''
+
+permissions:
+  contents: read
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          ref: ${{ inputs.ref }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        with:
+          # The script's header pins its dependencies, so it is the cache key.
+          cache-dependency-glob: build/validate-libraries.py
+
+      - name: Validate catalog entries
+        run: ./build/validate-libraries.py

.github/workflows/zola-deploy.yml

@@ -17,8 +17,11 @@ permissions:
 jobs:
   build:
     runs-on: ubuntu-latest
+    outputs:
+      commit: ${{ steps.checkout.outputs.commit }}
     steps:
       - name: Checkout
+        id: checkout
         uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
         with:
           ref: ${{ github.event_name != 'pull_request' && 'main' || '' }}
@@ -54,11 +57,10 @@ jobs:
           repository: valkey-io/valkey-json
           path: valkey-json
 
-      - name: Init commands, topics and clients
+      - name: Init commands and topics
         run: |
           cd website
-          ./build/init-topics-and-clients.sh ../valkey-doc/topics \
-            ../valkey-doc/clients
+          ./build/init-topics.sh ../valkey-doc/topics
           ./build/init-commands.sh ../valkey-doc/commands \
             ../valkey/src/commands ../valkey-bloom/src/commands \
             ../valkey-json/src/commands ../valkey-search/src/commands
@@ -76,13 +78,22 @@ jobs:
         with:
           path: ./website/public
 
+  validate:
+    needs: build
+    if: github.event_name != 'pull_request'
+    uses: ./.github/workflows/validate-libraries.yml
+    with:
+      ref: ${{ needs.build.outputs.commit }}
+    permissions:
+      contents: read
+
   deploy:
     if: github.event_name != 'pull_request'
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}
     runs-on: ubuntu-latest
-    needs: build
+    needs: [build, validate]
     steps:
       - name: Deploy to GitHub Pages
         id: deployment

.gitignore

@@ -7,7 +7,6 @@ build-command-json
 build-json-command-json
 build-search-command-json
 build-topics
-build-clients
 content/commands/*
 !content/commands/_index.md
 content/topics/*

README.md

@@ -26,19 +26,34 @@ Open your browser to `http://127.0.0.1:1111/`
 Zola will automatically rebuild on changes to the template or any content stored in this repo.
 Changes to external content (command reference, documentation topics) require a restart of the Zola server process (`ctrl-c` then `zola serve` again, a browser refresh may also be needed).
 
+### Checking catalog entries
+
+The clients and integrations entries in `_data/libraries/` are checked by `build/validate-libraries.py`, against the rules in `_data/libraries/schema.json` and the SPDX license list.
+CI runs it on pull requests that change the catalog and before every deploy.
+To run it locally with [uv](https://docs.astral.sh/uv/), which installs the dependencies pinned in the script's `# /// script` header:
+
+```shell
+./build/validate-libraries.py
+```
+
+Without uv, install the dependencies listed in that header yourself, then run `python3 build/validate-libraries.py` with the Python version the header requires.
+
+The script downloads the SPDX license list, so it needs network access.
+
 ## Building additional content
 
-**By default, the site will build without documentation topics, command reference, or the clients page.**
-The content for documentation topics and the clients page are stored within the `valkey-io/valkey-doc` repo.
+**By default, the site will build without documentation topics or the command reference.**
+The content for documentation topics is stored within the `valkey-io/valkey-doc` repo.
 The content for the command reference page is in the `valkey-io/valkey` repo.
+The clients and integrations pages (`/clients/`, `/integrations/`) are built from `_data/libraries/` in this repo, so they need no other repo.
 
 If you want to build the site with this content, you'll need to have a local copy of `valkey-io/valkey-doc` and `valkey-io/valkey` _outside_ of this repo.
-Then follow the instructions to [build the documentation topics and clients](#building-the-documentation-topics-and-clients-page) and/or [build the command reference](#building-the-command-reference).
+Then follow the instructions to [build the documentation topics](#building-the-documentation-topics) and/or [build the command reference](#building-the-command-reference).
 The instructions show how to use scripts that create symbolic links to the `valkey-io/valkey-doc` and `valkey-io/valkey` repos as well as create a series of empty stub files that tell Zola to create pages.
 
-### Building the documentation topics and clients page
+### Building the documentation topics
 
-Documentation 'topics' (i.e. `/topics/keyspace/`, `/topics/encryption/`, `/topics/transactions/`) and the client libraries' data (i.e. `/client-page-clients/nodejs/valkey-glide`, `/client-page-clients/python/valkey-py`) sources content from `valkey-io/valkey-doc`.
+Documentation 'topics' (i.e. `/topics/keyspace/`, `/topics/encryption/`, `/topics/transactions/`) source content from `valkey-io/valkey-doc`.
 
 ```mermaid
 flowchart TD
@@ -52,12 +67,12 @@ First, stop the `zola serve` process if you're running it.
 From the root directory of this repo run:
 
 ```shell
-# You should only need to run this once or when you add a new topic/client.
-./build/init-topics-and-clients.sh ../valkey-doc/topics ../valkey-doc/clients
+# You should only need to run this once or when you add a new topic.
+./build/init-topics.sh ../valkey-doc/topics
 ```
 
 Then, restart Zola.
-Point your browser at `http://127.0.0.1:1111/topics/` and you should see the fully populated list of topics and clients.
+Point your browser at `http://127.0.0.1:1111/topics/` and you should see the fully populated list of topics.
 All files created in this process are ignored by git.
 Commit your changes to your local copy of `valkey-io/valkey-doc`.
 

_data/lang_colors.toml

@@ -0,0 +1,60 @@
+# Language chip colors for the client/integration catalog (see templates/libraries.html).
+#
+# Colors are the per-language "color" values from GitHub Linguist's
+# lib/linguist/languages.yml, which is MIT-licensed data (colors, not logos), so
+# there is no trademark exposure — unlike bundling brand logos. See:
+#   https://github.com/github-linguist/linguist/blob/main/lib/linguist/languages.yml
+#   https://github.com/github-linguist/linguist/blob/main/LICENSE  (MIT)
+#
+# Each entry is keyed by the language slug the template computes from the
+# `language` field (lowercased; `#` -> `-sharp`, `.` and spaces -> `-`), e.g.
+# "C#" -> "c-sharp", "Node.js" -> "node-js".
+#
+# Fields:
+#   color   — chip background (Linguist hex).
+#   fg      — chip text/monogram color; use "#000" on light chips, "#fff" on dark.
+#   mono    — 1-2 char monogram shown in the badge.
+#
+# Note: Node.js is a runtime, not a Linguist language, so it has no Linguist
+# color of its own; we reuse the JavaScript color (#f1e05a) for the "node-js"
+# slug since Node.js clients are JavaScript/TypeScript.
+
+[python]
+color = "#3572A5"
+fg = "#fff"
+mono = "Py"
+
+[node-js]
+color = "#f1e05a"
+fg = "#000"
+mono = "Js"
+
+[java]
+color = "#b07219"
+fg = "#fff"
+mono = "Jv"
+
+[c-sharp]
+color = "#178600"
+fg = "#fff"
+mono = "C#"
+
+[go]
+color = "#00ADD8"
+fg = "#fff"
+mono = "Go"
+
+[php]
+color = "#4F5D95"
+fg = "#fff"
+mono = "PHP"
+
+[swift]
+color = "#F05138"
+fg = "#fff"
+mono = "Sw"
+
+[ruby]
+color = "#701516"
+fg = "#fff"
+mono = "Rb"

_data/libraries/clients/iovalkey.json

@@ -0,0 +1,20 @@
+{
+  "name": "iovalkey",
+  "language": "Node.js",
+  "license": "MIT",
+  "description": "A friendly fork of a widely used Node.js client, tracking Valkey. Promise-based API, Lua scripting and cluster support.",
+  "repository": "https://github.com/valkey-io/iovalkey",
+  "documentation": "https://github.com/valkey-io/iovalkey/blob/v0.4.0/README.md#quick-start",
+  "installCommand": "npm install iovalkey",
+  "features": {
+    "replica": true,
+    "backoff": true,
+    "pubsub": true,
+    "scan": false,
+    "latency": false,
+    "az": false,
+    "csc": false,
+    "capa": false,
+    "pool": true
+  }
+}

_data/libraries/clients/phpredis.json

@@ -0,0 +1,20 @@
+{
+  "name": "phpredis",
+  "language": "PHP",
+  "license": "PHP-3.01",
+  "description": "A client implemented as a PHP extension in C. Supports clustering, Sentinel, client-side sharding and storing PHP sessions.",
+  "repository": "https://github.com/phpredis/phpredis",
+  "documentation": "https://github.com/phpredis/phpredis/blob/6.3.0/README.md#connect-open",
+  "installCommand": "pie install phpredis/phpredis",
+  "features": {
+    "replica": true,
+    "backoff": true,
+    "pubsub": false,
+    "scan": false,
+    "latency": false,
+    "az": false,
+    "csc": false,
+    "capa": false,
+    "pool": true
+  }
+}