Add JSON resolution fallback with available-* attribute support

.gitignore

@@ -7,6 +7,7 @@ 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/

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) {

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;
 }
 

src/helpers/resolve-resource.js

@@ -41,14 +41,15 @@ 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') {
     // Only log if we have page context (not during initial template compilation)
     if (page && resource === undefined) {
       logUnresolved('undefined', 'attribute not defined (check page attributes)', page, context, logger)
     }
-    return undefined
+    return fallbackUrl || undefined
   }
 
   // External URLs pass through
@@ -129,8 +130,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
   }

src/partials/head-meta.hbs

@@ -9,26 +9,57 @@
 {{#with (or site.components.streaming site.components.ROOT)}}
 <meta name="latest-redpanda-version" content="{{this.latest.version}}">
 {{/with}}
-{{!-- Properties JSON: use page's version for ROOT component, site latest for others --}}
+{{!--
+  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}}
-{{!-- ROOT component page: use this version's tag for both meta and URL --}}
-<meta name="latest-redpanda-tag" content="{{page.componentVersion.asciidoc.attributes.latest-redpanda-tag}}">
-<meta name="properties-json-url" content="{{resolve-resource (concat 'attachment$redpanda-properties-' page.componentVersion.asciidoc.attributes.latest-redpanda-tag '.json') component='ROOT' module='reference' version=page.version}}">
+{{!-- Streaming component: resolve against page's own version --}}
+{{#with (or page.componentVersion.asciidoc.attributes.available-properties-tag page.componentVersion.asciidoc.attributes.latest-redpanda-tag)}}
+<meta name="latest-redpanda-tag" content="{{this}}">
+<meta name="properties-json-url" content="{{resolve-resource (concat 'attachment$redpanda-properties-' this '.json') component='streaming' module='reference' version=@root.page.version fallback=(concat 'https://docs.redpanda.com/streaming/' @root.page.version '/reference/_attachments/redpanda-properties-' this '.json')}}">
+{{/with}}
 {{else}}
-{{!-- Non-ROOT component (cloud, connect): use ROOT's latest --}}
-{{#with site.components.ROOT}}
+{{!-- 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}}
-<meta name="latest-redpanda-tag" content="{{this.latest.asciidoc.attributes.latest-redpanda-tag}}">
-<meta name="properties-json-url" content="{{resolve-resource (concat 'attachment$redpanda-properties-' this.latest.asciidoc.attributes.latest-redpanda-tag '.json') component='ROOT' module='reference'}}">
+{{#with (or this.latest.asciidoc.attributes.available-properties-tag this.latest.asciidoc.attributes.latest-redpanda-tag)}}
+<meta name="latest-redpanda-tag" content="{{this}}">
+<meta name="properties-json-url" content="{{resolve-resource (concat 'attachment$redpanda-properties-' this '.json') component='streaming' module='reference' version=(or @root.site.components.streaming.latest.version @root.site.components.ROOT.latest.version) fallback=(concat 'https://docs.redpanda.com/streaming/' (or @root.site.components.streaming.latest.version @root.site.components.ROOT.latest.version) '/reference/_attachments/redpanda-properties-' this '.json')}}">
+{{/with}}
 {{/if}}
 {{/with}}
 {{/if}}
-{{!-- Redpanda Connect JSON for Bloblang tooltips --}}
-{{#with (or site.components.redpanda-connect site.components.connect)}}
+{{!--
+  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}}
-<meta name="connect-json-url" content="{{resolve-resource (concat 'attachment$connect-' this.latest.asciidoc.attributes.latest-connect-version '.json') component='redpanda-connect' module='components'}}">
+{{#with (or this.latest.asciidoc.attributes.available-connect-version this.latest.asciidoc.attributes.latest-connect-version)}}
+<meta name="connect-json-url" content="{{resolve-resource (concat 'attachment$connect-' this '.json') component='connect' module='components' version=(or @root.site.components.connect.latest.version @root.site.components.redpanda-connect.latest.version) fallback=(concat 'https://docs.redpanda.com/connect/components/_attachments/connect-' this '.json')}}">
+{{/with}}
 {{/if}}
 {{/with}}
+{{!-- Opt-out: page authors can set :disable-property-tooltips: to suppress tooltips --}}
 {{#if page.attributes.disable-property-tooltips}}
 <meta name="disable-property-tooltips" content="true">
 {{/if}}