Property and enterprise macros: showcase

Set cloud_storage_enabled to enable Tiered Storage.

The name is checked against the published property data at build time. The result is a marked <code> element carrying data-property-name, which is the only thing the docs UI decorates — so an ordinary backticked word never gets a tooltip by accident. That matters because five real property names are ordinary words: admin, brokers, rack, retries, and superusers.

Tune log_segment_size for larger segments.

You do not name the page. The build works out which page documents the property and links there. A link is only ever emitted when a page in this component documents it: nothing is borrowed from another doc set, and no target is guessed from the property’s scope, because a link the build cannot verify is a broken link.

The four fixture pages in this component each declare what they publish:

Claims are then ranked: a declared page first, then a property heading pulled in from a generated partial, then a bare heading that merely happens to match a property name. Without that ranking, any page titled = admin would claim the admin broker property from the page that documents it — and a page title generates no anchor, so the link and the tooltip URL would both point at nothing.

See the declared page^.

Enable write caching for lower latency.

The tooltip still describes write_caching_default; only the visible text changes, so a sentence can read naturally without losing the reference.

cloud_storage_cache_size

page= overrides discovery for the rare case a writer knows better. Note it supplies no tooltip documentation link, because the build has not verified the target — discovery would have provided one.

A bare name like that one stays module-relative within this component’s own reference module. Qualify it with a module (module:page) or a component and module (component:module:page) to point anywhere else the property is documented:

That target doesn’t exist in this sandbox, so it isn’t rendered live here — but the override is never build-verified either way, so a qualified target behaves exactly like the bare one above: nothing checks that cloud:reference:properties/cluster-properties.adoc actually exists or documents the property, until a reader clicks it.

not_a_real_property

Rendered as plain code, with no marker and therefore no tooltip, plus a build warning naming the file and offering close matches. A tooltip the build could not check is worse than none, because the reader has no way to tell it is wrong.

cloud_storage_max_partition_readers_per_shard

This property is deprecated. Every reference page filters out the deprecated include tag, so no page renders a heading for it, and there is nothing to link to: link=true renders unlinked and warns.

It keeps its tooltip, though, because the published data still describes the property accurately — including a deprecated badge, which the docs UI adds from the data’s is_deprecated field. That is the point of the distinction: a reader who meets a deprecated property in older prose still gets told what it was, without being sent to a reference page that deliberately omits it.

Note that the include tag and the data field are separate mechanisms. The tag decides whether a page renders the property; is_deprecated decides what the tooltip says. They agree here, and they should, but nothing enforces it — tagging a property deprecated in the partial without setting the field would hide it from every page while its tooltip claimed it was current.

Tiered Storage requires a licence.

The feature name is validated against the enterprise features registry, and the rendered term carries a tooltip explaining the licence requirement plus a link to the feature’s documentation.