From 83efabc76a615909b5035d5ca06f59c8bd3aaa2d Mon Sep 17 00:00:00 2001 From: JakeSCahill Date: Tue, 28 Jul 2026 11:30:57 +0100 Subject: [PATCH 1/2] Register set-available-attachment-versions extension Sets available-properties-tag / available-connect-version from what is actually in the content catalog so the UI's properties-json-url and connect-json-url meta tags never reference a JSON attachment that was not generated (top source of 404s: ~25k requests/day). Requires a docs-extensions-and-macros release containing redpanda-data/docs-extensions-and-macros#224. Co-Authored-By: Claude Fable 5 --- antora-playbook.yml | 4 ++++ local-antora-playbook.yml | 4 ++++ preview-antora-playbook.yml | 4 ++++ 3 files changed, 12 insertions(+) diff --git a/antora-playbook.yml b/antora-playbook.yml index 53541179..70a7a5c9 100644 --- a/antora-playbook.yml +++ b/antora-playbook.yml @@ -365,6 +365,10 @@ antora: - require: '@redpanda-data/docs-extensions-and-macros/extensions/generate-rp-connect-categories' - require: '@redpanda-data/docs-extensions-and-macros/extensions/modify-redirects' - require: '@redpanda-data/docs-extensions-and-macros/extensions/process-context-switcher' + # Point UI meta tags (properties-json-url, connect-json-url) at the newest + # generated JSON attachments that exist in the catalog, so version drift + # between release tags and generated JSON never produces 404 URLs + - require: '@redpanda-data/docs-extensions-and-macros/extensions/set-available-attachment-versions' - require: '@redpanda-data/docs-extensions-and-macros/extensions/algolia-indexer/index' excludes: ['.thumbs','script', '.page-versions','.feedback-section','.banner-container'] - require: '@redpanda-data/docs-extensions-and-macros/extensions/archive-attachments' diff --git a/local-antora-playbook.yml b/local-antora-playbook.yml index 4dd4f7b8..2f1f249c 100644 --- a/local-antora-playbook.yml +++ b/local-antora-playbook.yml @@ -290,6 +290,10 @@ antora: - require: '@redpanda-data/docs-extensions-and-macros/extensions/convert-to-markdown' - require: '@redpanda-data/docs-extensions-and-macros/extensions/add-llms-directive' - require: '@redpanda-data/docs-extensions-and-macros/extensions/process-context-switcher' + # Point UI meta tags (properties-json-url, connect-json-url) at the newest + # generated JSON attachments that exist in the catalog, so version drift + # between release tags and generated JSON never produces 404 URLs + - require: '@redpanda-data/docs-extensions-and-macros/extensions/set-available-attachment-versions' - require: '@redpanda-data/docs-extensions-and-macros/extensions/generate-index-data' data: sets: diff --git a/preview-antora-playbook.yml b/preview-antora-playbook.yml index 56234379..b5eefbdd 100644 --- a/preview-antora-playbook.yml +++ b/preview-antora-playbook.yml @@ -67,6 +67,10 @@ antora: - require: '@redpanda-data/docs-extensions-and-macros/extensions/convert-to-markdown' - require: '@redpanda-data/docs-extensions-and-macros/extensions/add-llms-directive' - require: '@redpanda-data/docs-extensions-and-macros/extensions/process-context-switcher' + # Point UI meta tags (properties-json-url, connect-json-url) at the newest + # generated JSON attachments that exist in the catalog, so version drift + # between release tags and generated JSON never produces 404 URLs + - require: '@redpanda-data/docs-extensions-and-macros/extensions/set-available-attachment-versions' - require: '@redpanda-data/docs-extensions-and-macros/extensions/generate-index-data' data: sets: From 897815d8e9c7486b245d1ea2c2b3ce4c7b4a8827 Mon Sep 17 00:00:00 2001 From: JakeSCahill Date: Mon, 3 Aug 2026 17:47:23 +0100 Subject: [PATCH 2/2] Unblock: bump doc-tools to 5.3.5 and register after version-fetcher Review findings on this PR and dem#224: - The lockfile resolved 5.0.0, which predates the extension file, so merging would have broken the build. doc-tools 5.3.5 (published today) ships it; floor and lockfile bumped, install verified to contain extensions/set-available-attachment-versions.js. - Registration moved after version-fetcher/set-latest-version in all three playbooks: both hook contentClassified and Antora dispatches in registration order, and the tooltip-disable branch reads latest-redpanda-tag. Registering first worked only because every antora.yml pins a fallback tag. --- antora-playbook.yml | 5 ++++- local-antora-playbook.yml | 5 ++++- package-lock.json | 10 +++++----- package.json | 2 +- preview-antora-playbook.yml | 5 ++++- 5 files changed, 18 insertions(+), 9 deletions(-) diff --git a/antora-playbook.yml b/antora-playbook.yml index 70a7a5c9..c5b40b1d 100644 --- a/antora-playbook.yml +++ b/antora-playbook.yml @@ -368,7 +368,6 @@ antora: # Point UI meta tags (properties-json-url, connect-json-url) at the newest # generated JSON attachments that exist in the catalog, so version drift # between release tags and generated JSON never produces 404 URLs - - require: '@redpanda-data/docs-extensions-and-macros/extensions/set-available-attachment-versions' - require: '@redpanda-data/docs-extensions-and-macros/extensions/algolia-indexer/index' excludes: ['.thumbs','script', '.page-versions','.feedback-section','.banner-container'] - require: '@redpanda-data/docs-extensions-and-macros/extensions/archive-attachments' @@ -400,6 +399,10 @@ antora: - require: '@redpanda-data/docs-extensions-and-macros/extensions/unlisted-pages' - require: '@redpanda-data/docs-extensions-and-macros/extensions/add-global-attributes' - '@redpanda-data/docs-extensions-and-macros/extensions/version-fetcher/set-latest-version' + # Registered after version-fetcher on purpose: this extension only sets + # attributes that are not already set, and its tooltip-disable branch reads + # latest-redpanda-tag, so the fetcher must run first. + - require: '@redpanda-data/docs-extensions-and-macros/extensions/set-available-attachment-versions' - require: '@redpanda-data/docs-extensions-and-macros/extensions/replace-attributes-in-attachments' data: replacements: diff --git a/local-antora-playbook.yml b/local-antora-playbook.yml index 2f1f249c..9f40c014 100644 --- a/local-antora-playbook.yml +++ b/local-antora-playbook.yml @@ -293,7 +293,6 @@ antora: # Point UI meta tags (properties-json-url, connect-json-url) at the newest # generated JSON attachments that exist in the catalog, so version drift # between release tags and generated JSON never produces 404 URLs - - require: '@redpanda-data/docs-extensions-and-macros/extensions/set-available-attachment-versions' - require: '@redpanda-data/docs-extensions-and-macros/extensions/generate-index-data' data: sets: @@ -332,6 +331,10 @@ antora: - require: '@redpanda-data/docs-extensions-and-macros/extensions/unlisted-pages' - require: '@redpanda-data/docs-extensions-and-macros/extensions/add-global-attributes' - '@redpanda-data/docs-extensions-and-macros/extensions/version-fetcher/set-latest-version' + # Registered after version-fetcher on purpose: this extension only sets + # attributes that are not already set, and its tooltip-disable branch reads + # latest-redpanda-tag, so the fetcher must run first. + - require: '@redpanda-data/docs-extensions-and-macros/extensions/set-available-attachment-versions' - require: '@redpanda-data/docs-extensions-and-macros/extensions/replace-attributes-in-attachments' data: replacements: diff --git a/package-lock.json b/package-lock.json index 30e00c14..33ff7802 100644 --- a/package-lock.json +++ b/package-lock.json @@ -12,7 +12,7 @@ "@asciidoctor/tabs": "^1.0.0-beta.5", "@modelcontextprotocol/sdk": "1.17.0", "@modelfetch/netlify": "0.15.2", - "@redpanda-data/docs-extensions-and-macros": "^5.0.0", + "@redpanda-data/docs-extensions-and-macros": "^5.3.5", "@sntke/antora-mermaid-extension": "^0.0.6", "algoliasearch": "^5.35.0", "hono-rate-limiter": "0.1.0", @@ -2029,9 +2029,9 @@ "license": "MIT" }, "node_modules/@redpanda-data/docs-extensions-and-macros": { - "version": "5.0.0", - "resolved": "https://registry.npmjs.org/@redpanda-data/docs-extensions-and-macros/-/docs-extensions-and-macros-5.0.0.tgz", - "integrity": "sha512-39rjNtv1oiHl/5vPYbkMwG+X6MYCc20868sfg4/Z5+WmcT0YcIuDtig/+CmbMHBmvuucRrUClk6DBYAtsUXoYQ==", + "version": "5.3.5", + "resolved": "https://registry.npmjs.org/@redpanda-data/docs-extensions-and-macros/-/docs-extensions-and-macros-5.3.5.tgz", + "integrity": "sha512-5synHF3EltMlXxWF8lr6JVIp10BlKMvnnLV8v1gJeIVvH5+W4jlk6Y/QpOmlpbPrq4KyawaY2+EmxpPGQ10lPQ==", "license": "ISC", "dependencies": { "@asciidoctor/tabs": "^1.0.0-beta.6", @@ -2041,7 +2041,7 @@ "@octokit/plugin-retry": "^7.1.1", "@octokit/rest": "^21.1.1", "@redocly/cli": "^2.2.0", - "ajv": "^8.12.0", + "ajv": "^8.20.0", "algoliasearch": "^4.17.0", "chalk": "4.1.2", "cheerio": "^1.1.2", diff --git a/package.json b/package.json index 7fbe626f..d29bf9e1 100644 --- a/package.json +++ b/package.json @@ -17,7 +17,7 @@ "@asciidoctor/tabs": "^1.0.0-beta.5", "@modelcontextprotocol/sdk": "1.17.0", "@modelfetch/netlify": "0.15.2", - "@redpanda-data/docs-extensions-and-macros": "^5.0.0", + "@redpanda-data/docs-extensions-and-macros": "^5.3.5", "@sntke/antora-mermaid-extension": "^0.0.6", "algoliasearch": "^5.35.0", "hono-rate-limiter": "0.1.0", diff --git a/preview-antora-playbook.yml b/preview-antora-playbook.yml index b5eefbdd..3194968f 100644 --- a/preview-antora-playbook.yml +++ b/preview-antora-playbook.yml @@ -70,7 +70,6 @@ antora: # Point UI meta tags (properties-json-url, connect-json-url) at the newest # generated JSON attachments that exist in the catalog, so version drift # between release tags and generated JSON never produces 404 URLs - - require: '@redpanda-data/docs-extensions-and-macros/extensions/set-available-attachment-versions' - require: '@redpanda-data/docs-extensions-and-macros/extensions/generate-index-data' data: sets: @@ -109,6 +108,10 @@ antora: - require: '@redpanda-data/docs-extensions-and-macros/extensions/unlisted-pages' - require: '@redpanda-data/docs-extensions-and-macros/extensions/add-global-attributes' - '@redpanda-data/docs-extensions-and-macros/extensions/version-fetcher/set-latest-version' + # Registered after version-fetcher on purpose: this extension only sets + # attributes that are not already set, and its tooltip-disable branch reads + # latest-redpanda-tag, so the fetcher must run first. + - require: '@redpanda-data/docs-extensions-and-macros/extensions/set-available-attachment-versions' - require: '@redpanda-data/docs-extensions-and-macros/extensions/replace-attributes-in-attachments' data: replacements: