Add property tooltips with xref-resolved JSON URLs

[JakeSCahill]

Summary

• Add property tooltips that display hover text for Redpanda configuration properties
• Use resolve-resource helper to dynamically resolve JSON attachment URLs
• Add warning logs when resource resolution fails

Preview: https://deploy-preview-373--docs-ui.netlify.app/property-tooltips-test

Test plan

• Tested with local Antora build
• Verified meta tags resolve to correct URLs
• Verified tooltips display on property pages

[netlify]

✅ Deploy Preview for docs-ui ready!

Name	Link
🔨 Latest commit	99a214d
🔍 Latest deploy log	https://app.netlify.com/projects/docs-ui/deploys/6a1ff9f8c212b60008dceb2c
😎 Deploy Preview	https://deploy-preview-373--docs-ui.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
Lighthouse	1 paths audited Performance: 29 (🔴 down 2 from production) Accessibility: 89 (no change from production) Best Practices: 100 (no change from production) SEO: 88 (no change from production) PWA: - View the detailed breakdown and full score reports

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[coderabbitai]

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 4ee7d31b-b53e-40d8-a9e2-6ba9f468cb72

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

📝 Walkthrough

Walkthrough

This pull request introduces property tooltips functionality for documentation pages. It adds a new CSS stylesheet defining tooltip styling with badge variants and dark mode support; a browser script that detects property-related code elements, loads property metadata from a JSON endpoint, caches it in localStorage, and attaches interactive Tippy.js tooltips with keyboard/touch event handlers; template updates that conditionally emit meta tags for configuration and resource URLs; and helper function changes to provide fallback resource resolution and logging for preview builds.

Sequence Diagram(s)

sequenceDiagram
    participant Page as Page Load
    participant Script as property-tooltips.js
    participant Meta as Meta Tags
    participant Cache as localStorage
    participant URL as Properties JSON<br/>Endpoint
    participant DOM as article.doc
    participant Tippy as Tippy.js

    Page->>Script: Load script
    Script->>Meta: Check enable-property-tooltips
    alt Tooltips Enabled
        Script->>Meta: Read properties-json-url
        Script->>Cache: Check 24h cache
        alt Cache Hit
            Cache-->>Script: Metadata object
        else Cache Miss
            Script->>URL: Fetch properties JSON
            URL-->>Script: Property metadata
            Script->>Cache: Store in localStorage
        end
        Script->>DOM: Scan code elements
        loop For each matching element
            Script->>DOM: Add CSS classes & ARIA attrs
            Script->>Tippy: Attach tooltip instance
            Script->>Tippy: Configure keyboard/touch handlers
        end
        Tippy-->>DOM: Render tooltip on interaction
    else Tooltips Disabled
        Script->>Script: Skip initialization
    end

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• Add AI-friendly meta tags and enhanced structured data #371: Modifies src/partials/head-meta.hbs to emit additional meta tags, overlapping with this PR's template changes.

Suggested reviewers

• kbatuigas
• paulohtb6
• Feediver1

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main change: adding property tooltips with dynamically resolved JSON URLs via xref resolution.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Description check	✅ Passed	The pull request description accurately summarizes the changeset, covering property tooltips addition, resource resolution helper improvements, and warning logs.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch xref-json-resolution

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (3)

src/css/property-tooltips.css (2)

83-109: Hardcoded badge colors may not align with the design system.

The badge colors use hardcoded hex values (e.g., #fff3cd, #856404 for restart badge) rather than CSS variables. This could cause visual inconsistency if the site's color palette changes.

Consider extracting these into CSS variables for consistency:

♻️ Optional: Use CSS variables for badge colors

 /* Restart required badge */
 .property-doc-tooltip .prop-badge-restart {
-  background: `#fff3cd`;
-  color: `#856404`;
-  border: 1px solid `#ffeeba`;
+  background: var(--badge-warning-bg, `#fff3cd`);
+  color: var(--badge-warning-color, `#856404`);
+  border: 1px solid var(--badge-warning-border, `#ffeeba`);
 }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/css/property-tooltips.css` around lines 83 - 109, Replace hardcoded hex
colors in the .property-doc-tooltip badge rules with CSS variables so badges
follow the design system; update .prop-badge-restart, .prop-badge-enterprise,
.prop-badge-deprecated, and .prop-badge-self-hosted to use --badge-bg-*,
--badge-color-*, and --badge-border-* variables (with sensible fallbacks) and
ensure these variables are defined at a root or .property-doc-tooltip scope so
they can be overridden by the global theme.

---

210-215: Negative margins may cause layout issues.

The negative margins (margin: -6px -3px) expand the tap target but could cause overlap with adjacent elements or affect text flow unexpectedly.

Consider using position: relative with padding instead, which achieves the same tap target expansion without affecting document flow:

♻️ Safer tap target expansion

 `@media` (hover: none) and (pointer: coarse) {
   code.has-property-tooltip {
-    padding: 6px 3px;
-    margin: -6px -3px;
+    position: relative;
+  }
+  
+  code.has-property-tooltip::before {
+    content: '';
+    position: absolute;
+    inset: -6px -3px;
   }
 }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/css/property-tooltips.css` around lines 210 - 215, Negative margins on
the selector code.has-property-tooltip expand the tap target but risk
overlapping neighbors; remove margin: -6px -3px and instead keep the larger
padding, make the element establish its own box (e.g., display: inline-block)
and add position: relative to visually expand the tap area without impacting
document flow, and if needed tweak vertical-align or line-height to preserve
baseline alignment; update the rule for code.has-property-tooltip in the touch
media query accordingly.

src/js/19-property-tooltips.js (1)

259-263: Regex replacement after escaping is safe but could produce invalid HTML with nested backticks.

The regex /([^]+)/ghandles simple backtick-wrapped text, but input like ``foobarbaz`` after escaping would producefoobarbaz`, which might not be the intended rendering.

This is a minor edge case—if property descriptions are well-formed, this won't be an issue.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/js/19-property-tooltips.js` around lines 259 - 263, In formatDescription,
the current regex runs after escaping and can mis-handle nested or multiple
backtick spans; change the algorithm to first locate and extract single-backtick
code spans in text (e.g., scan for matching backtick pairs in
formatDescription), replace each span with a temporary placeholder, then escape
the entire text with escapeHtml, and finally replace placeholders with unescaped
<code>...</code> fragments (ensuring the code contents are properly escaped or
sanitized as needed). This preserves intended code spans without producing
invalid nested HTML and references the formatDescription function and escapeHtml
helper for locating the fix.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@src/js/19-property-tooltips.js`:
- Around line 349-357: The init function currently checks window.tippy
synchronously and can falsely bail out if Tippy.js is still loading; update init
(and its early-return logic around isPropertyTooltipsEnabled) to wait briefly
for Tippy to become available before giving up — e.g., wrap the window.tippy
check in requestIdleCallback (with a fallback to setTimeout) or implement a
short retry loop that checks window.tippy a few times (with small delays) and
only logs the warning/returns if still missing after retries; reference the init
function and the isPropertyTooltipsEnabled check when making this change.
- Around line 238-241: The doc link currently builds docUrl with a hardcoded
'/current/' segment which breaks versioned docs; change the docUrl construction
to prepend a dynamic version string (e.g., read from a known page context/global
such as window.DOC_VERSION, window.pageContext.docVersion, or a <meta> tag) and
fall back to 'current' if missing, then use that variable instead of the literal
'current' when creating docUrl (update the code around prop.configScope, docUrl,
and the escapeHtml(...) call so the link uses the resolved version).

---

Nitpick comments:
In `@src/css/property-tooltips.css`:
- Around line 83-109: Replace hardcoded hex colors in the .property-doc-tooltip
badge rules with CSS variables so badges follow the design system; update
.prop-badge-restart, .prop-badge-enterprise, .prop-badge-deprecated, and
.prop-badge-self-hosted to use --badge-bg-*, --badge-color-*, and
--badge-border-* variables (with sensible fallbacks) and ensure these variables
are defined at a root or .property-doc-tooltip scope so they can be overridden
by the global theme.
- Around line 210-215: Negative margins on the selector
code.has-property-tooltip expand the tap target but risk overlapping neighbors;
remove margin: -6px -3px and instead keep the larger padding, make the element
establish its own box (e.g., display: inline-block) and add position: relative
to visually expand the tap area without impacting document flow, and if needed
tweak vertical-align or line-height to preserve baseline alignment; update the
rule for code.has-property-tooltip in the touch media query accordingly.

In `@src/js/19-property-tooltips.js`:
- Around line 259-263: In formatDescription, the current regex runs after
escaping and can mis-handle nested or multiple backtick spans; change the
algorithm to first locate and extract single-backtick code spans in text (e.g.,
scan for matching backtick pairs in formatDescription), replace each span with a
temporary placeholder, then escape the entire text with escapeHtml, and finally
replace placeholders with unescaped <code>...</code> fragments (ensuring the
code contents are properly escaped or sanitized as needed). This preserves
intended code spans without producing invalid nested HTML and references the
formatDescription function and escapeHtml helper for locating the fix.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: a471299c-0ebb-4922-a70f-8c5f5864ba2f

📥 Commits

Reviewing files that changed from the base of the PR and between c694140 and 499d746.

📒 Files selected for processing (4)

• src/css/property-tooltips.css
• src/helpers/resolve-resource.js
• src/js/19-property-tooltips.js
• src/partials/head-meta.hbs

[micheleRP]

Scope check + coverage concern for property-dense pages

Two follow-ups after digging into the feature in more detail.

1. Topic properties are covered, but the "View full documentation" link is likely broken for dotted property names

Good news: the tooltip covers all three scopes, not just cluster properties. Verified against redpanda-properties-v26.1.5.json:

• 540 cluster properties
• 73 broker properties
• 47 topic properties

redpanda.storage.mode is specifically in the dataset as a topic-scope property (alongside the cluster-wide default default_redpanda_storage_mode). The matching code in src/js/19-property-tooltips.js:386-390 is scope-agnostic — it just checks whether any <code> on the page has trimmed text matching a key in the JSON, so dotted names trigger the tooltip fine.

Caveat: the "View full documentation" link is unlikely to work correctly for dotted topic-property names. From src/js/19-property-tooltips.js:280-282:

var scope = prop.configScope || 'cluster'
var version = getDocVersion()
var docUrl = '/' + version + '/reference/properties/' + scope + '-properties/#' + prop.name.replace(/_/g, '-')

For redpanda.storage.mode, this produces …/topic-properties/#redpanda.storage.mode. That's almost certainly not the anchor AsciiDoc auto-generates for the === redpanda.storage.mode heading in topic-properties.adoc — the docs themselves already use two different manual slug conventions for this exact property:

• topic-properties.adoc:952 — <<redpandastorage-mode, ...>>
• topic-property-mappings.adoc:66 — <<redpandastoragemode, ...>>

Result: clicking "View full documentation" on a dotted topic-property tooltip probably lands on …/topic-properties/ and the browser silently falls back to the top of the page because the fragment doesn't resolve. Underscored cluster/broker names (log_retention_ms → log-retention-ms) should be fine, as long as Antora uses idseparator: '-' for heading auto-IDs.

Suggested fix: extend the anchor slugification to handle dots as well, and validate the slug convention against what AsciiDoc actually generates for the target pages. Worth testing on the deploy preview before merge by clicking through a topic-property tooltip.

2. High-property-density pages may need opt-out review

Some docs pages are dense with backticked property names — enabling tooltips on all of them by default could be visually overwhelming (hover flicker, noise while scanning). Concrete example:

• manage:tiered-storage.adoc (which includes manage:partial$tiered-storage.adoc) has 35 distinct property-name <code> mentions that would all match the tooltip dataset and trigger. That's on one page.

Two options worth considering before this rolls out broadly:

• Post-merge review pass: after merge, walk through the top property-dense pages (Tiered Storage, Cluster maintenance, Authentication, etc.) on the deploy preview and decide per-page whether the tooltip density reads as helpful or noisy.
• Opt-out by default on known-dense pages: set :page-disable-property-tooltips: on pages that are effectively property catalogs already. The machinery is already there (head-meta.hbs:32-34 → isPropertyTooltipsDisabled() at 19-property-tooltips.js:21-24), so it's just an attribute per page.

Not blocking the PR, but worth a plan for the rollout so the first feedback isn't "there are tooltips everywhere on Tiered Storage and it's distracting."

[JakeSCahill]

Addressed feedback

1. Fixed dotted property anchor slugification

Updated the anchor generation to match AsciiDoc's auto-ID behavior:

• Dots are removed (not replaced with hyphens)
• Underscores become hyphens

Examples:

• redpanda.storage.mode → #redpandastoragemode
• log_retention_ms → #log-retention-ms

Commit: 39bace1

2. Property-dense pages strategy

Agreed on the post-merge review pass approach. The opt-out mechanism is already in place:

:page-disable-property-tooltips: true

After merge, I'll review these known property-dense pages and disable tooltips where the density is distracting:

• manage:tiered-storage.adoc
• Cluster maintenance pages
• Authentication pages
• Other property catalog-style pages

This keeps the default behavior (tooltips enabled) for most pages while allowing targeted opt-out.

[Feediver1]

Docs standards review (UI/theme PR)

Files reviewed: 20 (CSS, JS, HBS partials, gulp task, workflow, JSON data file, preview test page). Not an .adoc content PR — review focuses on correctness, build health, and the long-standing review feedback.

What this PR does

Introduces a property-tooltips feature that detects Redpanda configuration property names in backticked <code> elements on documentation pages and attaches Tippy.js hover tooltips showing the property's description, default, type, restart requirement, and a "View full documentation" link. The data source is a JSON attachment (redpanda-properties-*.json) resolved via head-meta.hbs meta tags; the script caches metadata in localStorage for 24h. Also ships:

• New src/js/19-property-tooltips.js (486 lines), src/css/property-tooltips.css (203 lines), and an opt-out mechanism via the :page-disable-property-tooltips: page attribute.
• A vendored src/static/redpanda-properties.json (105 lines) as a static fallback for preview/local builds.
• A new .github/workflows/validate-build.yml adding timeouts to the existing Bundle UI / Lint Go steps.
• A preview-src/property-tooltips-test.adoc test page to exercise the tooltip behavior in the UI bundle's preview build.

Relationship to #384

PR #384 (the "available-* attribute" hardening I reviewed earlier today) extends this PR. #384 adds the (or available-* latest-*) fallback pattern on top of the URL-resolution introduced here. They touch overlapping code (head-meta.hbs, resolve-resource.js); whichever lands first will force a rebase of the other. Jake's "merge together" guidance on #384 only makes sense if #373 lands first. Worth confirming the intended merge sequence — most likely: #373 → docs-extensions-and-macros#200 → docs-ui#384.

Critical issues

1. Build is failing. The validate-build workflow's Bundle UI step times out after 15 minutes. The 15-minute timeout was added in this PR's commit "Prevents workflow hangs when steps intermittently freeze: Bundle UI: 15-minute timeout (normal: 5.5 minutes). Recent pattern: 11 of 30 runs cancelled after 64+ minute hangs." — meaning the timeout is the guardrail, but it's firing. This is either (a) a real hang in the bundle pipeline (in which case the timeout is preventing CI from running for an hour, but the underlying bundle hang is still unresolved), or (b) the bundle now genuinely takes longer than 15 minutes due to changes in this PR. Either way, CI is red and the PR can't merge in this state. Root-cause on the hang is needed before merge, not just a higher timeout.

2. CodeRabbit's Tippy.js timing race (line 349-357 of 19-property-tooltips.js) is still open. The init() function checks window.tippy synchronously and bails out with a warning if it's undefined. If Tippy.js is loaded asynchronously (defer/async script, or later script tag), init() may run before Tippy is available and the entire feature silently disables for users with slower script loading. CodeRabbit's suggestion (short retry with requestIdleCallback fallback) is sound and would make the feature robust. Worth fixing before merge.

Suggestions (CodeRabbit nits with merit)

1. Badge colors are hardcoded hex (#fff3cd, #856404, etc.) rather than using the theme's CSS variables. If the design system color palette changes (e.g., dark mode badge tokens get added), these badges won't move with it. Extract to var(--badge-warning-bg, #fff3cd) etc. so theme overrides work.

2. Negative margins for touch-target expansion (margin: -6px -3px on code.has-property-tooltip inside the touch-pointer media query) work but can collide with adjacent inline elements. CodeRabbit's inset: -6px -3px on a positioned pseudo-element is a cleaner pattern that doesn't disturb document flow.

3. Backtick regex in formatDescription runs after escapeHtml, so inputs like `foo`bar`baz` produce <code>foo</code>bar<code>baz</code> — not necessarily wrong, but rendering is ambiguous when descriptions contain nested or sequential backtick spans. Probably fine for the current property dataset (descriptions are usually clean), but a placeholder → escape → restore pattern would be more defensive.

What's been addressed

Two big substantive concerns from the 2026-04-21 review thread have been resolved:

• Dotted-property anchor slugification. Original code generated …#redpanda.storage.mode for the "View full documentation" link, which doesn't match AsciiDoc's auto-ID convention. Commit 39bace1 today fixed it to drop dots and convert underscores to hyphens, producing #redpandastoragemode and #log-retention-ms correctly.
• Property-dense pages strategy. The opt-out via :page-disable-property-tooltips: is wired up (HBS → meta → JS skip path). The post-merge review pass on the worst offenders (Tiered Storage, etc.) to selectively disable tooltips is a reasonable rollout plan as long as someone tracks it after merge.
• /current/ hardcoding (early CodeRabbit concern). getDocVersion() now reads the version from window.location.pathname (/25.3/... or /current/...) with a 'current' fallback for unversioned URLs. Versioned docs work.

Impact on related work

• The merge order with #384 and docs-extensions-and-macros#200 matters. This PR has to land first because both other PRs build on the URL-resolution it introduces.
• Post-merge rollout work: walking through property-dense pages (Tiered Storage, cluster maintenance, authentication) on the production deploy to decide where to set the opt-out attribute. Worth opening a tracking issue so it doesn't get forgotten.
• The vendored src/static/redpanda-properties.json is a snapshot — it'll drift from upstream. Worth a comment in the file (or a note in gulp.d/tasks/build-preview-pages.js) explaining that it's for preview/local-build fallback only and isn't expected to be kept in sync.

CodeRabbit findings worth considering

1. Tippy.js timing race — flagged as Critical 2 above.
2. /current/ hardcoding — ✓ already addressed by getDocVersion().
3. Hardcoded badge colors — Suggestion 1.
4. Negative margins for tap target — Suggestion 2.
5. Backtick regex edge case — Suggestion 3.

What works well

• Clear separation of data, presentation, and behavior: JSON data file, CSS module, JS module, HBS meta-tag wiring — each layer has its own file.
• 24h localStorage cache is a sensible balance between freshness and avoiding repeated JSON fetches.
• Opt-out attribute (:page-disable-property-tooltips:) is the right escape hatch for property-dense pages — and the machinery (HBS → meta → JS) is fully wired.
• getDocVersion() extracts the active version from URL — versioned docs land on the correct anchor.
• Test page (preview-src/property-tooltips-test.adoc) lets reviewers actually click through the feature in the deploy preview, not just read code.
• Long review thread shows real iteration: the 2026-04-21 coverage check + anchor-slugification concern was concrete, technical, and has been addressed substantively.

Process notes

• PR is two months old. With recent activity (today's commit + comment) the conversation is live again, but worth recognizing that a 1447-line feature PR sitting open for two months is harder for new reviewers to pick up. If you want this to merge, a tight cycle on the remaining items (build hang, Tippy timing, three CSS/JS nits) over a few days is better than letting it drift again.
• No human approval yet. With CI red, that's blocked; once the build is fixed, this needs at least one approver.

[Feediver1]

Delta review on the deltas since 2026-06-01

@JakeSCahill — re-reviewed after the merge-from-main commit landed today. Two retractions to record, one confirmation, and three polish items still open.

Status of my prior findings

Item	Status
Critical 1: Build failure (Bundle UI timing out at 15 min)	✅ RESOLVED. Latest run shows validate-build: success. The merge from main fixed it (probably brought in a pipeline change that allowed the bundle to complete within the timeout).
Critical 2: CodeRabbit's Tippy.js timing race	✅ Already addressed — retracting this one from my first review. Looking at the current code at src/js/19-property-tooltips.js:448-475, there's a full retry mechanism: 5 retries × 100ms delay, requestIdleCallback fallback, warning if Tippy doesn't load. This was added in commit 757a1e1 from 2026-04-10 — well before my first review. I flagged something that had already been fixed. Apologies for the noise.
Suggestion 1: Hardcoded badge hex colors	❌ Still present. #fff3cd, #856404, #d4edda, #155724, #f8d7da, #721c24 all unchanged.
Suggestion 2: Negative margins on tap target	❌ Still present. margin: -6px -3px at line 201 inside the (hover: none) and (pointer: coarse) media query.
Suggestion 3: Backtick regex edge case in formatDescription	❌ Still present. Line 330: var withCode = escaped.replace(/\([^\`]+)`/g, '$1')` — same pattern CodeRabbit flagged.

Verdict on "Is everything sufficiently addressed?"

Critical concerns: yes, all addressed. Build is green; Tippy timing race was already fixed two months ago (my flag was a false alarm).

Suggestions: no, all three open. The three CSS/JS polish items (hardcoded colors, negative margins, backtick regex) have not been touched since my last review. Whether to gate merge on them is a judgment call — none are correctness issues; they're maintainability/robustness improvements.

What's worth flagging beyond status-tracking

1. PR is two months old and has no human approval. Substantive work has been done since at least 2026-04-10. The recent merge from main suggests this PR is being kept alive but the review queue isn't moving. Worth pinging an approver explicitly if you want this to land.

2. Scope unchanged from my last review — still 19 files, ~1445+/488- lines covering the property-tooltips feature plus the various sidebar / back-to-top / algolia / etc. polish items from June 1. Same scope-creep concern as last time, just no new escalation.

3. Process note still applies: this PR is the foundation that #384 and docs-extensions-and-macros#200 build on. Merge ordering is unchanged: #373 first, then docs-extensions-and-macros#200, then docs-ui#384.

Suggestions (forward-looking, not regression)

1. Get a human approver in front of this PR. Substantive work is done; what's missing is review momentum, not code.
2. Decide whether the three open polish items are merge-blockers or follow-up. If follow-up, open an issue tracking them so they don't get lost. If blocker, land them as a single small commit (~20 LoC total).
3. Once this merges, kick off the follow-up audit of property-dense pages (Tiered Storage, cluster maintenance, authentication) per the original plan, to set :page-disable-property-tooltips: where the density would be distracting.