Make property tooltips opt-in via prop macro markers - #415
Open
JakeSCahill wants to merge 4 commits into
Open
Conversation
Contributor
|
Important Review skippedAuto reviews are disabled on base/target branches other than the default branch. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Plus Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
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. Comment |
Property tooltips previously decorated every inline code element whose text matched a property name, so ambiguous words such as admin, brokers, rack, retries, and superusers picked up tooltips in unrelated contexts (the admin listener in Helm values, audit-logging settings). Tooltips now decorate only elements emitted by the prop: AsciiDoc macro (class property-ref plus data-property-name), which validates names against the published property JSON at build time. The lookup name comes from data-property-name, so display text overrides keep working. The test page simulates macro output with pass-through HTML and asserts the old false-positive cases stay undecorated.
…pages Config properties are published in several components (streaming, cloud, and sometimes agentic-data-plane and connect), but the tooltip's View full documentation link hardcoded streaming's URL space, so cloud pages linked back into streaming. head-meta now emits a properties-pages-url meta tag resolved through resolve-resource WITHOUT an explicit component, so it resolves reference:properties/cluster-properties.adoc in the current page's own component and version. The tooltip swaps the property's scope into that URL. Components without property pages omit the tag (and unresolved preview placeholders are ignored), falling back to the previous streaming-relative behavior.
JakeSCahill
force-pushed
the
prop-macro-opt-in
branch
from
August 8, 2026 18:08
fa52324 to
6ed53d6
Compare
Generated property descriptions can contain prop macro calls (the property extractor now emits them for cross-property references), and older published JSONs still carry legacy config_ref calls. Both previously showed as raw macro text inside tooltips. The description formatter now renders them as code, honoring the prop macro's text= display override and config_ref's payload.
The properties-pages-url meta resolves a property reference page in the current page's own component, which legitimately does not exist for most components (home, labs, connect, search, and older versions with the flat layout). Those misses produced eight unresolved-resource warnings per build. A caller that passes fallback= (even an empty one) declares the resolution optional and handles the miss itself, so the helper no longer logs for it.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
In plain English
Property tooltips used to appear on any inline code that happened to match a property name -- including ordinary words like
adminthat mean something else on Helm and Kubernetes pages, so readers saw confident, wrong tooltips. From now on, the UI only decorates code that the docs'prop:macro explicitly marked (and the macro verified the name at build time), so a tooltip can be trusted: someone said it's a property, and the build checked. The tooltip's "view full documentation" link now also stays inside whichever doc set the reader is in (cloud pages link to cloud's property pages, not streaming's), and macro text that leaks into tooltip descriptions renders as clean code instead of raw markup. The trade during rollout: tooltips are briefly absent from prose until the companion docs PR lands -- absent, never wrong.Full explainer:
macros/PROPERTY_AND_ENTERPRISE_REFERENCES.adocin docs-extensions-and-macros#254.Description
Companion to redpanda-data/docs-extensions-and-macros#254 (the
prop:macro). Stacked on #413 — merge that first.Property tooltips currently decorate every
<code>element whose text matches a property name. The published JSON contains 5 separator-free names (admin,brokers,rack,retries,superusers) that are common words in Helm/Kubernetes/Connect contexts —admingets a Broker-property tooltip where it actually means an audit-logging value in the Helm chart.19-property-tooltips.jsnow selects onlycode[data-property-name]/code.property-ref— the markers theprop:macro emits after validating the name against the same published JSON at build time. The lookup key comes fromdata-property-name, so display-text overrides keep working. Everything else (tooltip content, enterprise lock styling, touch/keyboard a11y) is unchanged.The preview test page simulates macro output with pass-through HTML and now includes explicit negative cases: real property names in plain backticks (the old auto-match behavior) must stay undecorated, as must a marked element with an unknown name.
Validation
gulp lintclean,preview:buildrenders 11 marked elements on the test page./property-tooltips-test— marked names get tooltips (including the dotted and enterprise ones), the "Unmarked property names" section gets none.Rollout note: tooltips disappear from docs prose until the docs repo runs
doc-tools generate migrate-property-refsand registers the macro (companion docs PR does both in one change), so these should merge close together.