feat(crd-docs): mark beta CRDs with (beta) heading suffix and badge

[JakeSCahill]

The gap

The auto-generated modules/reference/pages/k-crd.adoc carries no beta indicators for beta CRDs. Pipeline, StretchCluster, and ShadowLink are beta features in operator 26.2, but their sections render unmarked in the otherwise-GA reference page.

The convention

Per the team convention for beta features inside an otherwise-GA page:

• A plain (beta) suffix on the section heading (no macros in headings, which leak markup into the TOC and anchors).
• A badge::[label=beta] badge at the start of the section body.
• :page-beta: is not used because the page as a whole is GA.

Design choice: template-level marking, driven by one editable pattern

The marking is implemented in the docs-side crd-ref-docs template (.github/crd-config/templates/asciidoctor/operator/type.tpl), keyed on a single commented pattern at the top of the template:

{{- $betaTypePattern := "^(Pipeline|Stretch|Shadow)" -}}

Why the template rather than a post-processing step or a betaKinds entry in .github/crd-config/config.yaml:

• Every regen path flows through these templates. The generate-crd.yml workflow, the doc-tools generate crd-spec command (its default --templates-dir is this directory), and manual crd-ref-docs runs all consume .github/crd-config/templates/asciidoctor/operator. A post-processing step would have to be wired into each of those paths separately and would silently drop off any path that forgets it. The config paths do NOT converge the same way: the workflow and doc-tools both pull the crd-ref-docs config from the operator repo, so .github/crd-config/config.yaml here is not consumed by any regen path today, and a betaKinds list there would be dead config.
• crd-ref-docs cannot pass custom config values into templates, so the list lives as a clearly commented one-line pattern in the template itself. Writers edit that one line when a feature graduates to GA or a new beta CRD ships. crd-ref-docs v0.1.0 (the version pinned in the workflow) ships Sprig, so regexMatch is available (verified by running the real binary).
• No operator repo changes (no godoc edits, no operator-side markers).

The pattern uses prefixes rather than exact kind names because each beta CRD brings a family of generated type sections that are all beta: Pipeline* (6 sections), Stretch* (17 sections, including StretchListeners, StretchStorage, and other StretchCluster config types that do not start with StretchCluster), and Shadow* (21 sections, including ShadowTopicState/ShadowTopicStatus which do not start with ShadowLink). Verified against the full 221-section output that no GA type matches the pattern.

This PR also registers @redpanda-data/docs-extensions-and-macros/macros/badge in local-antora-playbook.yml so local previews render the badge. The production docs-site playbooks already register it.

Anchor stability

The templates emit an explicit [id="..."] anchor line above every heading, so the heading text does not participate in ID generation:

[id="{anchor_prefix}-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-pipeline"]
== Pipeline (beta)

badge::[label=beta]

Proof from a real render (not just the source): generated the page before and after the change, converted both with Asciidoctor (with the real badge macro from docs-extensions-and-macros registered), and diffed the 221 <h2 id="..."> values. Byte-identical. Heading text differs only by the (beta) suffix on the 44 beta sections. Existing xrefs such as xref:reference:k-crd.adoc#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-pipeline keep resolving unchanged.

Validation

Ran the real generation locally with crd-ref-docs v0.1.0 (same version and flags as generate-crd.yml), against two operator sources, using the same GA ignore config as the #1817/#1830 regens:

• operator/v26.2.1-beta.3 tag (204 sections, StretchCluster + ShadowLink, no Pipeline because that tag predates the Pipeline CRD merge)
• operator main (221 sections, includes Pipeline, same source Regenerate CRD reference with the Pipeline CRD #1830 regenerated from)

Old templates vs new templates, on the operator-main output:

Check	Result
[id=...] anchor lines in the .adoc	byte-identical (diff clean)
<h2 id> values in rendered HTML	byte-identical, all 221
Sections gaining (beta) heading suffix	44, all matching ^(Pipeline|Stretch|Shadow)
badge::[label=beta] lines added	44, one per beta section, all converting to <span class="badge badge--beta"> in the render
Beta-family sections missed	0
GA sections changed	0 (every diff hunk is a beta heading suffix, a badge line, or surrounding blank line)

Example rendered output for the Pipeline section:

<h2 id="k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-pipeline">Pipeline (beta)</h2>
...
<p><span class="badge badge--beta ">(beta)</span></p>
<p>Pipeline defines a Redpanda Connect pipeline managed by the operator.</p>

What this PR does not do

k-crd.adoc itself is not regenerated here. #1830 (open, also based on beta) already regenerates it from operator main to add the Pipeline CRD. Regenerating in this PR too would duplicate and conflict with that work. After this merges, rerunning the #1830 regen with these templates (a single crd-ref-docs command) picks up the beta markers, and every future regen keeps them.

If the same marking is wanted on main (its 26.1 reference contains ShadowLink sections), the template change can be cherry-picked there with the pattern adjusted to the 26.1 beta set.

🤖 Generated with Claude Code

[netlify]

✅ Deploy Preview for redpanda-docs-preview ready!

Name	Link
🔨 Latest commit	015ddeb
🔍 Latest deploy log	https://app.netlify.com/projects/redpanda-docs-preview/deploys/6a687bacc8abbf0008390cc8
😎 Deploy Preview	https://deploy-preview-1833--redpanda-docs-preview.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

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 Plus

Run ID: b6f2f705-f766-4516-8452-8bf10fc6c38a

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/crd-beta-marking

---

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