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	ad66bde
🔍 Latest deploy log	https://app.netlify.com/projects/docs-ui/deploys/69e7935168a58f0009f4d970
😎 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: 36 (🔴 down 1 from production) Accessibility: 93 (no change from production) Best Practices: 83 (🔴 down 9 from production) SEO: 89 (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: 369c9cf7-7fb4-4eb3-99ac-fc672f5974c7

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."