Learn the prop: and enterprise: macros

By the end of this page you will have:

  • Marked a configuration property in prose, watched the build reject a name it can’t verify, then made that same name real and linked it — by editing the actual data, not the macro call.

  • Watched an unrecognized enterprise feature name render as plain text, the same way an unrecognized property does, then registered it for real, marked it unreleased, and watched this page refuse to publish it — the exact protection this system exists for.

This is a hands-on course, not a reference: sections 2 and 4 ask you to edit two local files and rebuild. Nothing here can break a real doc set — everything you’ll touch is fixture data in this checkout. Rebuild after every step with:

./scripts/macro-showcase.sh --serve

Read macro-showcase.log after each rebuild — that log is not a debugging aid you go looking for later, it’s the thing telling you what to do next. Every macro warning is tagged with the macro’s name (WARN (prop-macro): …​, WARN (enterprise-macro): …​), Antora’s own logger doing the tagging, not the macro formatting its own output. The excerpts below show HH:MM:SS.mmm in place of the real timestamp, which is different every time you rebuild.

1. Read the reference first (five minutes)

Before touching anything, see everything both macros do: the macro showcase walks every call, its rendered output, and why. Skim it now. You’ll recognize the mechanisms in the exercises below.

2. Exercise: mark a property that doesn’t exist yet

This paragraph writes prop:sandbox_example_property[] — rendered: sandbox_example_property

Step 1 — see it fail. Rebuild if you haven’t yet. The name above isn’t in any property data, so it renders as plain code, and the build log says exactly that:

[HH:MM:SS.mmm] WARN (prop-macro): prop:sandbox_example_property[] in
modules/ROOT/pages/macros-course.adoc: 'sandbox_example_property' is not in the
property data this page validates against (redpanda-properties-v26.2.1.json from
preview@unversioned). Either the name is misspelled or the property does not exist
in that release.

Step 2 — make the name real. Open preview/extensions-and-macros/modules/reference/attachments/redpanda-properties-v26.2.1.json. write_caching_default is the last entry in "properties", so add a comma after its closing }, then paste this entry right after it, before the closing } of "properties" itself:

"sandbox_example_property": {
  "name": "sandbox_example_property",
  "description": "Practice property for the macros course. Not a real Redpanda property.",
  "config_scope": "cluster",
  "cloud_supported": true,
  "type": "boolean",
  "default": false
}

Only config_scope and cloud_supported change macro behavior (they drive the Cloud availability gate — see Release status fixtures and the cloud fixture below); the rest is schema a real property file always carries. Rebuild. The warning is gone, and the marked-up mention above now shows a hover tooltip — the same <code> element with data-property-name that the docs UI decorates.

Step 3 — link it. Add link=true to the live mention at the top of this section, so it reads prop:sandbox_example_property[link=true], then rebuild. New warning, because a tooltip and a link are different questions: the name validates, but no page documents it, so link=true has nowhere to point:

[HH:MM:SS.mmm] WARN (prop-macro): prop:sandbox_example_property[link=true] in
modules/ROOT/pages/macros-course.adoc: 'sandbox_example_property' is in
redpanda-properties-v26.2.1.json from preview@unversioned but no reference page in
this component renders a heading for it, so it keeps its tooltip and renders
without a link.

Open preview/extensions-and-macros/modules/reference/partials/properties/preview-properties.adoc. Inside the category-cluster tagged region (anywhere between write_caching_default and the deprecated block is fine), add:

=== sandbox_example_property

Practice property for the macros course. Not a real Redpanda property.

Rebuild. The mention above now links to the cluster properties page — discovered, not hardcoded: nothing you touched named that page.

Clean up (optional). git checkout — preview/extensions-and-macros/modules/reference/attachments/redpanda-properties-v26.2.1.json preview/extensions-and-macros/modules/reference/partials/properties/preview-properties.adoc puts both files back so the next person starts from the same failing state you did.

3. The beta-workflow gates (reference)

Two more things can go wrong with an enterprise feature besides "does it exist": is it public yet (status) and has this specific page’s version shipped it (since). Both are already exercising themselves, live, in this build — no editing needed:

  • Released fixtures (26.2) and beta fixtures (26.3) are two versions of the same component. Flip the version selector between them and watch three identical macro calls render three different ways, purely from where each page’s version sits relative to the registry.

  • Release status gating shows the same unreleased/beta contrast from a third, versionless component.

  • Cloud fixtures shows the separate availability gate: cloud_supported, checked regardless of version or branch.

Section 4 has you reproduce the status: unreleased gate yourself, on this page.

4. Exercise: register a brand-new enterprise feature

This paragraph writes enterprise:Sandbox Example Feature[] — rendered: Sandbox Example Feature

Step 1 — see it render safely. Rebuild if you haven’t yet, then hover the mention above — there’s nothing to hover. It renders as plain text, exactly like prop: does for a property name that doesn’t exist: no styling, no tooltip, no link to guess at. enterprise: has nothing to style an unrecognized name with, so it doesn’t. The build log says why:

[HH:MM:SS.mmm] WARN (enterprise-macro): enterprise:Sandbox Example Feature[] does
not match any feature in the enterprise features registry in
modules/ROOT/pages/macros-course.adoc. Add the feature to enterprise-features.yml
in the shared component first.

Now register it for real, and compare.

Step 2 — register it for real. Open preview/shared/modules/ROOT/partials/enterprise-features.yml. Add an entry to the features list (indentation matters — match the entries around it):

  - name: Sandbox Example Feature
    scope: redpanda
    tooltip: Registered for real now -- this text comes from the registry.
    description: |
      Practice feature for the macros course. Not a real Redpanda feature.
    expiration: |
      The feature is disabled.

Rebuild and hover the mention again. It’s styled now — a tooltip and a link to the licensing page — because a real registry entry backs it, and the build warning is gone. Before this step it was plain text with nothing to hover; a registered name is the only thing that earns styling. No status key at all means GA: available everywhere, on every version, with no badge.

Step 3 — mark it unreleased. Add one line to the entry you just wrote:

    status: unreleased

Rebuild. The styling is gone again — back to plain text — and the log explains why:

[HH:MM:SS.mmm] WARN (enterprise-macro): enterprise:Sandbox Example Feature[] in
modules/ROOT/pages/macros-course.adoc: 'Sandbox Example Feature' is marked
status: unreleased in the enterprise features registry, so it is only documented
for an upcoming release. This page belongs to a released version, so the mention
renders as plain text with no enterprise styling, tooltip, or link. Move the
mention to the prerelease (beta) branch, or change the status once the feature
ships.

That is the entire beta-workflow protection, and you just triggered it on purpose: this page is a released version, so an unreleased feature cannot be styled here, no matter what the mention itself says.

Step 4 (optional) — see the other side. Open preview/macro-fixtures-beta/modules/ROOT/pages/index.adoc — a real prerelease fixture (prerelease: true in its antora.yml) — and add a line calling the macro on Sandbox Example Feature exactly as you did on this page in step 2. Rebuild and look at /macro-fixtures/26.3/: it renders styled, with an unreleased badge. Same registry entry, same macro call, different result, because that page’s version is a prerelease. Revert the fixture file afterward: git checkout — preview/macro-fixtures-beta/modules/ROOT/pages/index.adoc.

Clean up (optional). git checkout — preview/shared/modules/ROOT/partials/enterprise-features.yml removes the entry you added.

5. What to do with this on a real page

Everything above is the mechanism. For the actual writer-facing procedure — when to use status: unreleased vs status: beta vs since, what to generate before you can mention an RC-only property, and a pre-PR checklist — see macros/DOCUMENTING_UNRELEASED_FEATURES.adoc in this repo (not part of this build; open it in your checkout or on GitHub).