Opt-in property tooltips through the prop macro - #1896
Draft
JakeSCahill wants to merge 4 commits into
Draft
Conversation
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). Registers the prop macro with property-validate: warn and applies the one-time migration (doc-tools generate migrate-property-refs): 647 property mentions across 86 hand-written files become prop:name[] macros, validated against the published redpanda-properties JSON. Autogenerated content (rpk pages, CRD and Helm specs, property partials) is untouched, and the five ambiguous separator-free names are deliberately left as plain code.
Contributor
|
Important Review skippedDraft detected. 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 |
The config_ref macro prefixed every property with storage.tiered.config
on Kubernetes pages, which mislabels non-tiered properties: the chart's
documented home for general cluster properties is config.cluster (the
docs recommend it for all cluster properties, including Tiered Storage
ones). Its manual path argument is also redundant now that the prop
macro discovers reference pages dynamically.
All 147 hand-written config_ref calls become prop calls with
helm-path=auto, which derives the per-property correct Helm values path
on env-kubernetes renders: storage.tiered.config.* stays for tiered
storage properties (matching the k-tiered-storage examples), broker
properties map to config.node.*, and other cluster properties now
correctly display config.cluster.* instead of storage.tiered.config.*.
Two manual fixes on top of the codemod: a single-use {config-ref}
attribute indirection is inlined, and the table row for
cloud_storage_reconciliation_interval_ms is removed because that
property no longer exists in Redpanda (the row already said Deprecated;
the macro validation caught that the name is absent from the published
JSON).
config_ref remains only inside the generated property partials until
the property extractor emits prop macros itself.
… published JSON Converts the config_ref calls in docs-data/property-overrides.json (the source the extractor merges into descriptions), the current generated partials, and the published property JSON attachments to prop macro calls, matching what the fixed property extractor now emits on regeneration. The attachment conversion also fixes tooltips that showed raw config_ref macro text in the descriptions of properties such as delete.retention.ms. No config_ref call sites remain anywhere in current content. The macro stays registered only for older version branches, which still contain it in their generated partials.
This was referenced Aug 9, 2026
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
This flips property tooltips from "the UI guesses what's a property" to "writers say so and the build verifies it." Every genuine property mention in hand-written prose (647 of them) is now explicitly marked with the
prop:macro, each name validated against the published property data at build time -- and the five property names that are ordinary English words (admin,brokers,rack,retries,superusers) are deliberately left unmarked, because those are exactly the ones that produced wrong tooltips on Helm and Kubernetes pages. The oldconfig_refmacro is gone from current content: it never checked names and displayed a tiered-storage Helm path on every property on Kubernetes pages, so the live site showedstorage.tiered.config.log_segment_sizefor a setting whose documented home isconfig.cluster. Its replacement derives the correct path per property. The conversion also caught real rot: a table still documenting a property that no longer exists in Redpanda, and raw macro text leaking into tooltip descriptions from the published JSON -- both fixed here.Full explainer for the team:
macros/PROPERTY_AND_ENTERPRISE_REFERENCES.adocin docs-extensions-and-macros#254.Description
Companion to redpanda-data/docs-extensions-and-macros#254 (the
prop:macro) and redpanda-data/docs-ui#415 (the UI cutover). Stacked on #1895 — draft until docs-extensions-and-macros 5.7.0 publishes and the docs-ui bundle with #415 releases.Property tooltips currently decorate every inline
codeelement matching a property name. The published JSON has 5 separator-free names (admin,brokers,rack,retries,superusers) that are common words in Helm/Kubernetes contexts —admingets a broker-property tooltip where it means an audit-logging value in the Helm chart.prop:macro withproperty-validate: warn— targets are validated at build time against the publishedredpanda-properties-<tag>.json(the same attachment the tooltips fetch).prop:name[]. Autogenerated content (rpk pages, k-crd, Helm specs, property partials) untouched; the 5 ambiguous names deliberately left as plain code — writers can mark them explicitly where they really mean the property.tags=redpanda-cloudfilters), so cloud/adp/connect pages link to their own property pages, and links keep working if the property reference is ever split across new pages.config_scopeis only the deterministic fallback.Validation
Full local Antora build against a packed 5.7.0 tarball: exit 0, zero unknown-property warnings (every converted name validates), spot-checked pages render
data-property-namemarkers (51 on disk-utilization alone, including dotted topic properties).Merge order
The UI cutover (#415) and this PR should land close together: between them, tooltips are absent from prose (opt-in markers exist but the old bundle ignores them — harmless), never wrong.
Update — config_ref replaced too. All 147 hand-written
config_refcalls are converted topropcalls withhelm-path=auto. This fixes a live mislabeling:config_refprefixed every property withstorage.tiered.config.on Kubernetes renders, so the k-tiered-storage page showedstorage.tiered.config.log_segment_size— the per-property derivation now displaysconfig.cluster.log_segment_sizethere while genuine tiered properties keepstorage.tiered.config.*. Two manual fixes rode along: a single-use{config-ref}attribute indirection is inlined, and the table row forcloud_storage_reconciliation_interval_msis removed (the property no longer exists in Redpanda — caught by the macro's JSON validation).config_refnow appears only inside the generated property partials, pending a property-extractor follow-up.