Add a manifest of the page attributes the UI reads

.github/workflows/publish-release.yml

@@ -50,7 +50,7 @@
             GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           run: |
             TAG="${{ github.ref_name }}"
-            ASSET=./build/ui-bundle.zip
+            ASSET="./build/ui-bundle.zip ./src/ui-attributes.json"
             FLAGS="--generate-notes"
             if [[ "$TAG" =~ - ]]; then
               FLAGS+=" --prerelease"

.github/workflows/validate-build.yml

@@ -95,6 +95,12 @@ jobs:
         run: npm run test:hero-scroll
       - name: Test docs page weight (lazy images, trimmed Prism, on-demand highlighting, head)
         run: npm run test:docs-page-weight
+      - name: Test the UI attribute manifest matches the templates
+        run: npm run test:ui-attributes
+      - name: Test templates read page attributes without the page- prefix
+        run: npm run test:page-attribute-prefix
+      - name: Test malformed JSON attributes do not fail the build
+        run: npm run test:json-attribute-guard
       - name: Test the introduced-in version badge
         run: npm run test:introduced-in-badge
       - name: Test the Ask AI latest-version tool

CLAUDE.md

@@ -76,6 +76,7 @@ The project uses Gulp 4 with task definitions in `gulpfile.js` and task implemen
 - `font/` - Web fonts
 - `img/` - Images and icons
 - `ui.yml` - Defines which static files to include in bundle
+- `ui-attributes.json` - Every page and component attribute the templates and helpers read, with type, values, and readers. Ships in the bundle and as a release asset for the docs language server. When a template or helper starts or stops reading an attribute, update this file; `npm run test:ui-attributes` fails until it matches
 
 ### WebAssembly Integration
 Two WASM modules built from Go:
@@ -98,7 +99,7 @@ The `compile-partial.js` script compiles specific Handlebars partials into stand
 Context is provided via JSON files in `context/` directory.
 
 ### Handlebars Templates
-Layouts select partials to compose pages. Helpers in `src/helpers/` provide template logic (e.g., `is-beta-feature.js`, `is-enterprise.js`, `get-page-info.js`). Pages specify layout via `page-layout` AsciiDoc attribute.
+Layouts select partials to compose pages. Helpers in `src/helpers/` provide template logic (e.g., `is-beta-feature.js`, `get-page-info.js`). Pages specify layout via `page-layout` AsciiDoc attribute.
 
 ### Preview System
 `preview-src/` contains AsciiDoc sample pages for testing UI locally. UI model is defined in `preview-src/ui-model.yml`. Preview pages are built with Asciidoctor and rendered using the UI templates.

gulp.d/tasks/build.js

@@ -59,6 +59,8 @@ module.exports = (src, dest, preview) => () => {
 
   return merge(
     vfs.src('ui.yml', { ...opts, allowEmpty: true }),
+    // Machine-readable list of the page attributes the templates read, for the docs language server.
+    vfs.src('ui-attributes.json', opts),
     vfs
       .src('js/+([0-9])-*.js', { ...opts, read: false, sourcemaps })
       .pipe(bundle(opts))

package.json

@@ -96,8 +96,11 @@
     "test:has-code-blocks": "node --test tests/has-code-blocks/*.test.js",
     "test:hero-scroll": "node --test tests/hero-scroll/*.test.js",
     "test:docs-page-weight": "node --test tests/docs-page-weight/*.test.js",
+    "test:ui-attributes": "node --test tests/ui-attributes/*.test.js",
+    "test:page-attribute-prefix": "node --test tests/page-attribute-prefix/*.test.js",
+    "test:json-attribute-guard": "node --test tests/json-attribute-guard/*.test.js",
     "test:callout-preservation": "npx gulp generate:prism && node tests/callout-preservation/test-runner.js",
-    "test:all": "npm run test:playground && npm run test:interactive && npm run test:negative-cache && npm run test:head-meta && npm run test:latest-version-tool && npm run test:introduced-in-badge && npm run test:property-tooltips && npm run test:signin-nudge && npm run test:chat-panel-navigation && npm run test:toc-collapsible && npm run test:toc-active-anchor && npm run test:nav-scroll && npm run test:kapa-source-groups && npm run test:tooltip-touch && npm run test:tooltip-single-open && npm run test:lazy-askai && npm run test:nav-lazy-buckets && npm run test:has-code-blocks && npm run test:docs-page-weight && npm run test:anon-quota && npm run test:callout-preservation",
+    "test:all": "npm run test:playground && npm run test:interactive && npm run test:negative-cache && npm run test:head-meta && npm run test:latest-version-tool && npm run test:introduced-in-badge && npm run test:property-tooltips && npm run test:signin-nudge && npm run test:chat-panel-navigation && npm run test:toc-collapsible && npm run test:toc-active-anchor && npm run test:nav-scroll && npm run test:kapa-source-groups && npm run test:tooltip-touch && npm run test:tooltip-single-open && npm run test:lazy-askai && npm run test:nav-lazy-buckets && npm run test:has-code-blocks && npm run test:docs-page-weight && npm run test:ui-attributes && npm run test:page-attribute-prefix && npm run test:json-attribute-guard && npm run test:anon-quota && npm run test:callout-preservation",
     "build:wasm": "cd blobl-editor/wasm && GOOS=js GOARCH=wasm go build -o ../../src/static/blobl.wasm .",
     "copy:wasm-exec": "cp \"$(go env GOROOT)/lib/wasm/wasm_exec.js\" src/js/vendor/",
     "serve:playground": "npx serve .",

preview-src/connect-test.adoc

@@ -1,6 +1,7 @@
 = Redpanda Connect
 :page-layout: component-home-v3
 :page-role: component-home-v3
+:page-commercial-names: Apache Kafka, Kafka
 :page-hero-color: #A21CAF
 :hero-description: Stream processing and data integration with 200+ connectors. Build real-time pipelines without writing code.
 :hero-ask-placeholder: Ask AI about Redpanda Connect...

src/helpers/add-suggested-labs.js

@@ -7,7 +7,7 @@ module.exports = (attributes, content, { data: { root } }) => {
   if (!contentCatalog) return content
 
   // Extract related labs from attributes
-  const relatedLabs = attributes['related-labs'] ? JSON.parse(attributes['related-labs']) : []
+  const relatedLabs = parseRelatedLabs(attributes['related-labs'], root)
 
   if (!relatedLabs.length) return content
 
@@ -55,3 +55,19 @@ module.exports = (attributes, content, { data: { root } }) => {
   const modifiedContent = Buffer.from(contentString, 'utf8')
   return modifiedContent
 }
+
+// Malformed page-related-labs JSON is logged and skipped instead of failing the build.
+function parseRelatedLabs (value, root) {
+  if (!value) return []
+  try {
+    const parsed = JSON.parse(value)
+    return Array.isArray(parsed) ? parsed : []
+  } catch (err) {
+    const { page, logger } = root || {}
+    const where = (page && page.src && page.src.path) || (page && page.relativeSrcPath) || 'unknown page'
+    const message = `${where}: ignoring malformed JSON in page-related-labs (${err.message})`
+    if (logger && typeof logger.warn === 'function') logger.warn(message)
+    else console.warn(`[add-suggested-labs] ${message}`)
+    return []
+  }
+}

src/helpers/get-ai-suggestions.js

@@ -37,9 +37,9 @@ module.exports = function (options) {
 
   // Collect up to 4 suggestions from component attributes
   for (let i = 1; i <= 4; i++) {
-    const key = `ai-suggestion-${i}`
-    if (attrs[key]) {
-      suggestions.push(attrs[key])
+    const suggestion = attrs[`ai-suggestion-${i}`]
+    if (suggestion) {
+      suggestions.push(suggestion)
     }
   }
 

src/helpers/list-related-labs.js

@@ -6,7 +6,7 @@ module.exports = (title, attributes, content, { data: { root } }) => {
   if (!contentCatalog) return content
 
   // Extract related labs from attributes
-  const relatedLabs = attributes['related-labs'] ? JSON.parse(attributes['related-labs']) : []
+  const relatedLabs = parseRelatedLabs(attributes['related-labs'], root)
   if (!relatedLabs.length) return content
 
   let contentString = content.toString('utf8')
@@ -20,3 +20,19 @@ module.exports = (title, attributes, content, { data: { root } }) => {
   const modifiedContent = Buffer.from(contentString, 'utf8')
   return modifiedContent
 }
+
+// Malformed page-related-labs JSON is logged and skipped instead of failing the build.
+function parseRelatedLabs (value, root) {
+  if (!value) return []
+  try {
+    const parsed = JSON.parse(value)
+    return Array.isArray(parsed) ? parsed : []
+  } catch (err) {
+    const { page, logger } = root || {}
+    const where = (page && page.src && page.src.path) || (page && page.relativeSrcPath) || 'unknown page'
+    const message = `${where}: ignoring malformed JSON in page-related-labs (${err.message})`
+    if (logger && typeof logger.warn === 'function') logger.warn(message)
+    else console.warn(`[list-related-labs] ${message}`)
+    return []
+  }
+}

src/helpers/obj.js

@@ -1,8 +1,20 @@
 'use strict'
 
-module.exports = (a) => {
+// Parses a JSON attribute value, such as page-context-switcher, page-faqs, or
+// toc-tools-links. Malformed JSON is logged and treated as empty so one bad
+// attribute cannot fail the whole site build.
+module.exports = (a, options) => {
   if (typeof a === 'undefined' || a === null) {
     return {}
   }
-  return JSON.parse(a)
+  try {
+    return JSON.parse(a)
+  } catch (err) {
+    const { page, logger } = (options && options.data && options.data.root) || {}
+    const where = (page && page.src && page.src.path) || (page && page.relativeSrcPath) || 'unknown page'
+    const message = `${where}: ignoring malformed JSON attribute value (${err.message}): ${String(a).slice(0, 80)}`
+    if (logger && typeof logger.warn === 'function') logger.warn(message)
+    else console.warn(`[obj] ${message}`)
+    return {}
+  }
 }

src/layouts/labs-home.hbs

@@ -115,11 +115,11 @@
         <div class="labs-hero-inner">
           <div class="labs-hero-eyebrow">
             <span class="labs-hero-dot"></span>
-            {{#if page.attributes.page-hero-eyebrow}}{{page.attributes.page-hero-eyebrow}}{{else}}Redpanda Labs{{/if}}
+            {{#if page.attributes.hero-eyebrow}}{{page.attributes.hero-eyebrow}}{{else}}Redpanda Labs{{/if}}
           </div>
-          <h1 class="labs-hero-title">{{#if page.attributes.page-hero-title}}{{page.attributes.page-hero-title}}{{else}}Real projects you can build with Redpanda.{{/if}}</h1>
+          <h1 class="labs-hero-title">{{#if page.attributes.hero-title}}{{page.attributes.hero-title}}{{else}}Real projects you can build with Redpanda.{{/if}}</h1>
           <p class="labs-hero-sub">
-            {{#if page.attributes.page-hero-subtitle}}{{page.attributes.page-hero-subtitle}}{{else}}Hands-on tutorials and example applications that show what's possible with Redpanda. Clone a repo, run the code, and learn by doing.{{/if}}
+            {{#if page.attributes.hero-subtitle}}{{page.attributes.hero-subtitle}}{{else}}Hands-on tutorials and example applications that show what's possible with Redpanda. Clone a repo, run the code, and learn by doing.{{/if}}
           </p>
           <div class="labs-hero-stats">
             <div>

src/partials/data-platform.hbs

@@ -62,7 +62,7 @@
   </header>
 
   {{!-- Cloud landing: component cards --}}
-  {{#if page.attributes.page-cloud-landing}}
+  {{#if page.attributes.cloud-landing}}
   <section class="dp-section dp-component-cards-section">
     <div class="dp-section-head">
       <h2 class="dp-section-title">{{#if page.attributes.component-cards-title}}{{page.attributes.component-cards-title}}{{else}}Choose your component{{/if}}</h2>

src/partials/head-info.hbs

@@ -25,8 +25,8 @@
     <meta property="og:description" content="Redpanda Documentation: Guides, API references, and resources for event streaming.">
     <meta name="twitter:description" content="Redpanda Documentation: Guides, API references, and resources for event streaming.">
     {{/if}}
-    {{#if (or page.keywords page.attributes.page-commercial-names)}}
-    <meta name="keywords" content="{{#with page.keywords}}{{{this}}}{{#if @root.page.attributes.page-commercial-names}}, {{/if}}{{/with}}{{#with page.attributes.page-commercial-names}}{{{this}}}{{/with}}">
+    {{#if (or page.keywords page.attributes.commercial-names)}}
+    <meta name="keywords" content="{{#with page.keywords}}{{{this}}}{{#if @root.page.attributes.commercial-names}}, {{/if}}{{/with}}{{#with page.attributes.commercial-names}}{{{this}}}{{/with}}">
     {{/if}}
     {{#with (or antoraVersion site.antoraVersion)}}
     <meta name="generator" content="Antora {{{this}}}">