From e0452613b7d8221c65c011ef9de49142beaf93a4 Mon Sep 17 00:00:00 2001 From: JakeSCahill Date: Mon, 1 Jun 2026 10:54:49 +0100 Subject: [PATCH 1/5] Add JSON resolution fallback with available-* attribute support Updates head-meta.hbs to use new available-properties-tag and available-connect-version attributes from the docs-extensions-and-macros package, with fallback to latest-* attributes for backwards compatibility. Changes: - head-meta.hbs: Use (or available-* latest-*) pattern for JSON URLs - resolve-resource.js: Add fallback URL parameter support - generate-bloblang-grammar.js: Fix Connect URL path (/connect/ not /redpanda-connect/) - ui.yml: Add static JSON fallback files The available-* attributes are set by set-latest-version extension to point to JSON files that actually exist in the content catalog, solving the issue where latest-* attributes may point to unreleased versions. Requires: redpanda-data/docs-extensions-and-macros#200 Co-Authored-By: Claude Opus 4.5 --- gulp.d/tasks/generate-bloblang-grammar.js | 2 +- src/helpers/resolve-resource.js | 8 ++++-- src/partials/head-meta.hbs | 32 +++++++++++++++++++++++ src/ui.yml | 2 ++ 4 files changed, 41 insertions(+), 3 deletions(-) diff --git a/gulp.d/tasks/generate-bloblang-grammar.js b/gulp.d/tasks/generate-bloblang-grammar.js index 572a0464..08c02acc 100644 --- a/gulp.d/tasks/generate-bloblang-grammar.js +++ b/gulp.d/tasks/generate-bloblang-grammar.js @@ -6,7 +6,7 @@ const log = require('fancy-log') const https = require('https') const ANTORA_YML_URL = 'https://raw.githubusercontent.com/redpanda-data/rp-connect-docs/main/antora.yml' -const CONNECT_JSON_BASE = 'https://docs.redpanda.com/redpanda-connect/components/_attachments' +const CONNECT_JSON_BASE = 'https://docs.redpanda.com/connect/components/_attachments' const FALLBACK_VERSIONS = ['4.79.0', '4.78.0', '4.77.0', '4.76.0', '4.75.0'] function fetchText (url) { diff --git a/src/helpers/resolve-resource.js b/src/helpers/resolve-resource.js index 8c2e70c3..f5197630 100644 --- a/src/helpers/resolve-resource.js +++ b/src/helpers/resolve-resource.js @@ -41,6 +41,7 @@ function logUnresolved (resource, reason, page, context, logger) { module.exports = (resource, { data, hash: context }) => { const { page, logger } = data.root || {} + const fallbackUrl = context?.fallback // Log and return undefined if resource is not provided if (!resource || typeof resource !== 'string') { @@ -48,7 +49,7 @@ module.exports = (resource, { data, hash: context }) => { if (page && resource === undefined) { logUnresolved('undefined', 'attribute not defined (check page attributes)', page, context, logger) } - return undefined + return fallbackUrl || undefined } // External URLs pass through @@ -108,8 +109,11 @@ module.exports = (resource, { data, hash: context }) => { if (file) { result = file.pub.url + } else if (fallbackUrl) { + // Use fallback URL when resource not in content catalog + result = fallbackUrl } else { - // Log warning for unresolved resource + // Log warning for unresolved resource (only if no fallback provided) logUnresolved(resolvedResource, 'target not found in content catalog', page, context, logger) result = resource } diff --git a/src/partials/head-meta.hbs b/src/partials/head-meta.hbs index d6e0281f..b8226145 100644 --- a/src/partials/head-meta.hbs +++ b/src/partials/head-meta.hbs @@ -9,4 +9,36 @@ {{#with (or site.components.streaming site.components.ROOT)}} {{/with}} +{{!-- Properties JSON: use page's version for streaming component, site latest for others --}} +{{!-- available-properties-tag is set by set-latest-version extension to the highest version with JSON in catalog --}} +{{#if page.componentVersion.asciidoc.attributes.latest-redpanda-tag}} +{{!-- Streaming component page: use available version if set, otherwise latest --}} +{{#with (or page.componentVersion.asciidoc.attributes.available-properties-tag page.componentVersion.asciidoc.attributes.latest-redpanda-tag)}} + + +{{/with}} +{{else}} +{{!-- Non-streaming component (cloud, connect): use streaming's latest --}} +{{#with (or site.components.streaming site.components.ROOT)}} +{{#if this.latest.asciidoc.attributes.latest-redpanda-tag}} +{{#with (or this.latest.asciidoc.attributes.available-properties-tag this.latest.asciidoc.attributes.latest-redpanda-tag)}} + +{{!-- Use streaming component's latest version for the fallback URL --}} + +{{/with}} +{{/if}} +{{/with}} +{{/if}} +{{!-- Redpanda Connect JSON for Bloblang tooltips --}} +{{!-- available-connect-version is set by set-latest-version extension to the highest version with JSON in catalog --}} +{{#with (or site.components.connect site.components.redpanda-connect)}} +{{#if this.latest.asciidoc.attributes.latest-connect-version}} +{{#with (or this.latest.asciidoc.attributes.available-connect-version this.latest.asciidoc.attributes.latest-connect-version)}} + +{{/with}} +{{/if}} +{{/with}} +{{#if page.attributes.disable-property-tooltips}} + +{{/if}} diff --git a/src/ui.yml b/src/ui.yml index 4aa8ab5a..3099650c 100644 --- a/src/ui.yml +++ b/src/ui.yml @@ -2,4 +2,6 @@ static_files: - blobl.wasm - console-config-migrator.wasm - ask-ai.html +- redpanda-properties.json +- connect.json - assets/** From 6d1680a2b087f378fb9e3e7816c0a603299ce8fe Mon Sep 17 00:00:00 2001 From: JakeSCahill Date: Tue, 2 Jun 2026 16:21:50 +0100 Subject: [PATCH 2/5] Add static JSON files for UI preview mode - Add sample redpanda-properties.json with representative properties - Track connect.json (already existed but was gitignored) - Update .gitignore to allow these preview-mode JSON files These files enable property tooltips and Bloblang playground to work in UI preview/development mode when the meta tags aren't populated by Antora. Addresses review feedback about static files in ui.yml. Co-Authored-By: Claude Opus 4.5 --- .gitignore | 2 + src/static/connect.json | 142 ++++++++++++++++++++++++++++ src/static/redpanda-properties.json | 40 ++++++++ 3 files changed, 184 insertions(+) create mode 100644 src/static/connect.json create mode 100644 src/static/redpanda-properties.json diff --git a/.gitignore b/.gitignore index eca39432..b0e39ede 100644 --- a/.gitignore +++ b/.gitignore @@ -6,6 +6,8 @@ blobl.wasm src/static/* !src/static/bloblang-docs.json !src/static/widget-test.html +!src/static/redpanda-properties.json +!src/static/connect.json test-results.* test-results-*.* .playwright-mcp/ diff --git a/src/static/connect.json b/src/static/connect.json new file mode 100644 index 00000000..4b903422 --- /dev/null +++ b/src/static/connect.json @@ -0,0 +1,142 @@ +{ + "bloblang-functions": [ + { + "name": "now", + "description": "Returns the current timestamp as a string.", + "category": "general", + "examples": [ + { + "mapping": "root.created_at = now()" + } + ] + }, + { + "name": "uuid_v4", + "description": "Generates a new RFC-4122 UUID v4 string.", + "category": "general", + "examples": [ + { + "mapping": "root.id = uuid_v4()" + } + ] + }, + { + "name": "env", + "description": "Returns the value of an environment variable.", + "category": "environment", + "params": { + "named": [ + { + "name": "name", + "type": "string", + "description": "The name of the environment variable." + } + ] + }, + "examples": [ + { + "mapping": "root.api_key = env(\"API_KEY\")" + } + ] + }, + { + "name": "throw", + "description": "Throws an error with a given message.", + "category": "general", + "params": { + "named": [ + { + "name": "message", + "type": "string", + "description": "The error message to throw." + } + ] + }, + "examples": [ + { + "mapping": "root = if this.value < 0 { throw(\"negative value\") }" + } + ] + } + ], + "bloblang-methods": [ + { + "name": "string", + "description": "Marshal a value into a string.", + "categories": [{"Category": "coercion"}], + "examples": [ + { + "mapping": "root.str = this.number.string()" + } + ] + }, + { + "name": "number", + "description": "Attempt to parse a value into a number.", + "categories": [{"Category": "coercion"}], + "examples": [ + { + "mapping": "root.num = this.str.number()" + } + ] + }, + { + "name": "uppercase", + "description": "Convert a string to uppercase.", + "categories": [{"Category": "strings"}], + "examples": [ + { + "mapping": "root.upper = this.name.uppercase()" + } + ] + }, + { + "name": "lowercase", + "description": "Convert a string to lowercase.", + "categories": [{"Category": "strings"}], + "examples": [ + { + "mapping": "root.lower = this.name.lowercase()" + } + ] + }, + { + "name": "contains", + "description": "Checks whether a string contains a substring.", + "categories": [{"Category": "strings"}], + "params": { + "named": [ + { + "name": "value", + "type": "string", + "description": "The substring to search for." + } + ] + }, + "examples": [ + { + "mapping": "root.has_foo = this.text.contains(\"foo\")" + } + ] + }, + { + "name": "map_each", + "description": "Apply a mapping to each element of an array.", + "categories": [{"Category": "object & array"}], + "params": { + "named": [ + { + "name": "mapping", + "type": "query", + "description": "The mapping to apply." + } + ] + }, + "examples": [ + { + "mapping": "root.doubled = this.numbers.map_each(num -> num * 2)" + } + ] + } + ] +} diff --git a/src/static/redpanda-properties.json b/src/static/redpanda-properties.json new file mode 100644 index 00000000..5c9d942f --- /dev/null +++ b/src/static/redpanda-properties.json @@ -0,0 +1,40 @@ +{ + "_comment": "Sample properties file for UI preview mode. In production, this is fetched from the docs site.", + "properties": { + "log_retention_ms": { + "name": "log_retention_ms", + "type": "integer", + "default": 604800000, + "description": "How long to keep log segments before deletion. See `delete.retention.ms` for topic-level configuration.", + "config_scope": "topic", + "needs_restart": false, + "is_deprecated": false, + "is_enterprise": false, + "visibility": "user", + "nullable": true + }, + "kafka_group_max_session_timeout_ms": { + "name": "kafka_group_max_session_timeout_ms", + "type": "integer", + "default": 300000, + "description": "Maximum allowed consumer group session timeout.", + "config_scope": "cluster", + "needs_restart": false, + "is_deprecated": false, + "is_enterprise": false, + "visibility": "user" + }, + "retention.bytes": { + "name": "retention.bytes", + "type": "integer", + "default": null, + "description": "Maximum size of a partition's log before old segments are deleted.", + "config_scope": "topic", + "needs_restart": false, + "is_deprecated": false, + "is_enterprise": false, + "visibility": "user", + "nullable": true + } + } +} From 283c61d5cfdede0819bfd120919e4c65dc5e2897 Mon Sep 17 00:00:00 2001 From: JakeSCahill Date: Tue, 2 Jun 2026 16:43:24 +0100 Subject: [PATCH 3/5] Fix resolve-resource to use explicit component versions - Add explicit version parameter to properties-json-url resolution for non-streaming pages (uses streaming's latest version) - Add explicit version parameter to connect-json-url resolution (uses connect's latest version) This ensures resolve-resource looks up attachments against the correct component version rather than inheriting from the current page context. Addresses CodeRabbit review comments about component/version context. Co-Authored-By: Claude Opus 4.5 --- src/partials/head-meta.hbs | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/src/partials/head-meta.hbs b/src/partials/head-meta.hbs index b8226145..4d874868 100644 --- a/src/partials/head-meta.hbs +++ b/src/partials/head-meta.hbs @@ -23,8 +23,8 @@ {{#if this.latest.asciidoc.attributes.latest-redpanda-tag}} {{#with (or this.latest.asciidoc.attributes.available-properties-tag this.latest.asciidoc.attributes.latest-redpanda-tag)}} -{{!-- Use streaming component's latest version for the fallback URL --}} - +{{!-- Use streaming component's latest version for resolution and fallback URL --}} + {{/with}} {{/if}} {{/with}} @@ -34,7 +34,8 @@ {{#with (or site.components.connect site.components.redpanda-connect)}} {{#if this.latest.asciidoc.attributes.latest-connect-version}} {{#with (or this.latest.asciidoc.attributes.available-connect-version this.latest.asciidoc.attributes.latest-connect-version)}} - +{{!-- Use connect component's latest version for resolution --}} + {{/with}} {{/if}} {{/with}} From e9be4a9e0f09a0492a6476a668b21d9966b74fb8 Mon Sep 17 00:00:00 2001 From: JakeSCahill Date: Thu, 4 Jun 2026 10:36:41 +0100 Subject: [PATCH 4/5] Address review feedback: remove unused static files, add docs - Remove unused redpanda-properties.json and connect.json from ui.yml (fallback URLs point to production, not static files) - Add detailed comments explaining: - Resolution strategy for properties/connect JSON - Version context differences (streaming vs non-streaming pages) - Why fallback URLs point to production - The disable-property-tooltips opt-out mechanism Co-Authored-By: Claude Opus 4.5 --- src/partials/head-meta.hbs | 37 ++++++-- src/static/connect.json | 142 ---------------------------- src/static/redpanda-properties.json | 40 -------- src/ui.yml | 2 - 4 files changed, 29 insertions(+), 192 deletions(-) delete mode 100644 src/static/connect.json delete mode 100644 src/static/redpanda-properties.json diff --git a/src/partials/head-meta.hbs b/src/partials/head-meta.hbs index 4d874868..3193ee8d 100644 --- a/src/partials/head-meta.hbs +++ b/src/partials/head-meta.hbs @@ -9,36 +9,57 @@ {{#with (or site.components.streaming site.components.ROOT)}} {{/with}} -{{!-- Properties JSON: use page's version for streaming component, site latest for others --}} -{{!-- available-properties-tag is set by set-latest-version extension to the highest version with JSON in catalog --}} +{{!-- + Properties JSON URL for property tooltips + + Resolution strategy: + 1. Use available-properties-tag (set by extension to highest version with JSON in catalog) + 2. Fall back to latest-redpanda-tag for backwards compatibility + 3. If resource not in catalog, fall back to production URL + + Version context: + - Streaming pages: Use page.version (readers on /25.3/ get 25.3's JSON) + - Non-streaming pages: Use streaming.latest.version (cloud/connect get latest streaming JSON) + + Fallback URLs point to production to ensure tooltips work even when: + - Running preview builds without full content catalog + - JSON hasn't been published yet for the specified version +--}} {{#if page.componentVersion.asciidoc.attributes.latest-redpanda-tag}} -{{!-- Streaming component page: use available version if set, otherwise latest --}} +{{!-- Streaming component: resolve against page's own version --}} {{#with (or page.componentVersion.asciidoc.attributes.available-properties-tag page.componentVersion.asciidoc.attributes.latest-redpanda-tag)}} {{/with}} {{else}} -{{!-- Non-streaming component (cloud, connect): use streaming's latest --}} +{{!-- Non-streaming (cloud, connect): resolve against streaming's latest version --}} {{#with (or site.components.streaming site.components.ROOT)}} {{#if this.latest.asciidoc.attributes.latest-redpanda-tag}} {{#with (or this.latest.asciidoc.attributes.available-properties-tag this.latest.asciidoc.attributes.latest-redpanda-tag)}} -{{!-- Use streaming component's latest version for resolution and fallback URL --}} {{/with}} {{/if}} {{/with}} {{/if}} -{{!-- Redpanda Connect JSON for Bloblang tooltips --}} -{{!-- available-connect-version is set by set-latest-version extension to the highest version with JSON in catalog --}} +{{!-- + Connect JSON URL for Bloblang tooltips + + Resolution strategy: + 1. Use available-connect-version (set by extension to highest version with JSON in catalog) + 2. Fall back to latest-connect-version for backwards compatibility + 3. If resource not in catalog, fall back to production URL + + Connect component is versionless, so URLs use /connect/components/... (no version segment) +--}} {{#with (or site.components.connect site.components.redpanda-connect)}} {{#if this.latest.asciidoc.attributes.latest-connect-version}} {{#with (or this.latest.asciidoc.attributes.available-connect-version this.latest.asciidoc.attributes.latest-connect-version)}} -{{!-- Use connect component's latest version for resolution --}} {{/with}} {{/if}} {{/with}} +{{!-- Opt-out: page authors can set :disable-property-tooltips: to suppress tooltips --}} {{#if page.attributes.disable-property-tooltips}} {{/if}} diff --git a/src/static/connect.json b/src/static/connect.json deleted file mode 100644 index 4b903422..00000000 --- a/src/static/connect.json +++ /dev/null @@ -1,142 +0,0 @@ -{ - "bloblang-functions": [ - { - "name": "now", - "description": "Returns the current timestamp as a string.", - "category": "general", - "examples": [ - { - "mapping": "root.created_at = now()" - } - ] - }, - { - "name": "uuid_v4", - "description": "Generates a new RFC-4122 UUID v4 string.", - "category": "general", - "examples": [ - { - "mapping": "root.id = uuid_v4()" - } - ] - }, - { - "name": "env", - "description": "Returns the value of an environment variable.", - "category": "environment", - "params": { - "named": [ - { - "name": "name", - "type": "string", - "description": "The name of the environment variable." - } - ] - }, - "examples": [ - { - "mapping": "root.api_key = env(\"API_KEY\")" - } - ] - }, - { - "name": "throw", - "description": "Throws an error with a given message.", - "category": "general", - "params": { - "named": [ - { - "name": "message", - "type": "string", - "description": "The error message to throw." - } - ] - }, - "examples": [ - { - "mapping": "root = if this.value < 0 { throw(\"negative value\") }" - } - ] - } - ], - "bloblang-methods": [ - { - "name": "string", - "description": "Marshal a value into a string.", - "categories": [{"Category": "coercion"}], - "examples": [ - { - "mapping": "root.str = this.number.string()" - } - ] - }, - { - "name": "number", - "description": "Attempt to parse a value into a number.", - "categories": [{"Category": "coercion"}], - "examples": [ - { - "mapping": "root.num = this.str.number()" - } - ] - }, - { - "name": "uppercase", - "description": "Convert a string to uppercase.", - "categories": [{"Category": "strings"}], - "examples": [ - { - "mapping": "root.upper = this.name.uppercase()" - } - ] - }, - { - "name": "lowercase", - "description": "Convert a string to lowercase.", - "categories": [{"Category": "strings"}], - "examples": [ - { - "mapping": "root.lower = this.name.lowercase()" - } - ] - }, - { - "name": "contains", - "description": "Checks whether a string contains a substring.", - "categories": [{"Category": "strings"}], - "params": { - "named": [ - { - "name": "value", - "type": "string", - "description": "The substring to search for." - } - ] - }, - "examples": [ - { - "mapping": "root.has_foo = this.text.contains(\"foo\")" - } - ] - }, - { - "name": "map_each", - "description": "Apply a mapping to each element of an array.", - "categories": [{"Category": "object & array"}], - "params": { - "named": [ - { - "name": "mapping", - "type": "query", - "description": "The mapping to apply." - } - ] - }, - "examples": [ - { - "mapping": "root.doubled = this.numbers.map_each(num -> num * 2)" - } - ] - } - ] -} diff --git a/src/static/redpanda-properties.json b/src/static/redpanda-properties.json deleted file mode 100644 index 5c9d942f..00000000 --- a/src/static/redpanda-properties.json +++ /dev/null @@ -1,40 +0,0 @@ -{ - "_comment": "Sample properties file for UI preview mode. In production, this is fetched from the docs site.", - "properties": { - "log_retention_ms": { - "name": "log_retention_ms", - "type": "integer", - "default": 604800000, - "description": "How long to keep log segments before deletion. See `delete.retention.ms` for topic-level configuration.", - "config_scope": "topic", - "needs_restart": false, - "is_deprecated": false, - "is_enterprise": false, - "visibility": "user", - "nullable": true - }, - "kafka_group_max_session_timeout_ms": { - "name": "kafka_group_max_session_timeout_ms", - "type": "integer", - "default": 300000, - "description": "Maximum allowed consumer group session timeout.", - "config_scope": "cluster", - "needs_restart": false, - "is_deprecated": false, - "is_enterprise": false, - "visibility": "user" - }, - "retention.bytes": { - "name": "retention.bytes", - "type": "integer", - "default": null, - "description": "Maximum size of a partition's log before old segments are deleted.", - "config_scope": "topic", - "needs_restart": false, - "is_deprecated": false, - "is_enterprise": false, - "visibility": "user", - "nullable": true - } - } -} diff --git a/src/ui.yml b/src/ui.yml index 3099650c..4aa8ab5a 100644 --- a/src/ui.yml +++ b/src/ui.yml @@ -2,6 +2,4 @@ static_files: - blobl.wasm - console-config-migrator.wasm - ask-ai.html -- redpanda-properties.json -- connect.json - assets/** From 269b3ff786ffce3850ca4743b659f1fc7d9be407 Mon Sep 17 00:00:00 2001 From: Jake Cahill <45230295+JakeSCahill@users.noreply.github.com> Date: Thu, 4 Jun 2026 16:02:15 +0100 Subject: [PATCH 5/5] Update doc.css --- src/css/doc.css | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/css/doc.css b/src/css/doc.css index 95b71421..9d997447 100644 --- a/src/css/doc.css +++ b/src/css/doc.css @@ -946,7 +946,7 @@ html[data-theme="dark"] .doc #preamble > .sectionbody > .paragraph:first-child > gap: 12px; padding: 14px 16px; border-radius: 10px; - font-size: calc(16 / var(--rem-base) * 1rem); + font-size: calc(17.5 / var(--rem-base) * 1rem); line-height: 1.55; }