@redpanda-data/docs-extensions-and-macros 5.8.0 → 5.10.0

package/extensions/util/scan-content-urls.js

@@ -0,0 +1,121 @@
+'use strict'
+
+/**
+ * Scans AsciiDoc content for http(s) URLs that appear in prose, skipping
+ * URLs inside code contexts where rewriting or checking them would be wrong:
+ *
+ * - delimited listing (----), literal (....), fenced (```), and passthrough
+ *   (++++) blocks
+ * - inline code spans (`...`)
+ *
+ * Each match records enough position information for a caller to splice a
+ * replacement into the original content.
+ *
+ * Match shape:
+ * - url: the URL with any trailing sentence punctuation trimmed
+ * - label: text of a directly attached AsciiDoc link label ([...]), or null.
+ *   A label may span line breaks, which is common in generated content where
+ *   long lines are wrapped; its newlines are collapsed to single spaces
+ * - start/end: absolute offsets in content covering the whole replaceable
+ *   span (including a leading link: macro prefix and the label, if present)
+ * - hasLinkPrefix: true when the URL was written as link:https://...[...]
+ * - inAttributeEntry: true when the URL appears in an attribute entry line
+ *   (for example ":url-docs: https://..."), where a caller may want to leave
+ *   the value untouched
+ * - inAttributeValue: true when the URL is a macro attribute value (for
+ *   example image:d.png[alt,link=https://...]); rewriting one of these to an
+ *   xref macro would corrupt the surrounding macro, but the URL is still a
+ *   real link target worth checking
+ */
+
+const URL_RX = /(link:)?(https?:\/\/[^\s\][)"'<>]+)(\[[^\]]*\])?/g
+// Sentence punctuation, and the AsciiDoc formatting markup that closes around a
+// URL written as *emphasis* or **bold** (`**https://example.com/page**`), which
+// is not part of the URL.
+const TRAILING_PUNCT_RX = /[.,;:!?*_]+$/
+const ATTRIBUTE_ENTRY_RX = /^:!?[a-zA-Z0-9_][a-zA-Z0-9_-]*!?:(?:\s|$)/
+// Cap on how far a wrapped label may run, so an unmatched bracket somewhere in
+// prose cannot swallow the rest of the document.
+const MAX_WRAPPED_LABEL_LENGTH = 500
+
+function blockDelimiter (line) {
+  if (/^-{4,}$/.test(line)) return '-'
+  if (/^\.{4,}$/.test(line)) return '.'
+  if (/^`{3,}$/.test(line)) return '`'
+  if (/^\+{4,}$/.test(line)) return '+'
+  return null
+}
+
+function scanContentUrls (content) {
+  const matches = []
+  const lines = content.split('\n')
+  let offset = 0
+  let openDelimiter = null
+  for (const rawLine of lines) {
+    const line = rawLine.endsWith('\r') ? rawLine.slice(0, -1) : rawLine
+    const delimiter = blockDelimiter(line)
+    if (delimiter) {
+      if (openDelimiter === delimiter) openDelimiter = null
+      else if (!openDelimiter) openDelimiter = delimiter
+    } else if (!openDelimiter) {
+      scanLine(line, offset, matches, content)
+    }
+    offset += rawLine.length + 1
+  }
+  return matches
+}
+
+/**
+ * Reads a link label that opens on this line but closes on a later one, which
+ * happens whenever a generator wraps long lines. Returns the label text with
+ * its line breaks collapsed, plus the offset just past the closing bracket.
+ * A blank line ends the search: that is a paragraph break, so the bracket
+ * belongs to something else.
+ */
+function readWrappedLabel (content, openIndex) {
+  if (content[openIndex] !== '[') return
+  const limit = Math.min(content.length, openIndex + MAX_WRAPPED_LABEL_LENGTH)
+  const closeIndex = content.indexOf(']', openIndex + 1)
+  if (closeIndex === -1 || closeIndex > limit) return
+  const raw = content.slice(openIndex + 1, closeIndex)
+  if (/\n[ \t]*\n/.test(raw)) return
+  return { label: raw.replace(/\s*\n\s*/g, ' '), end: closeIndex + 1 }
+}
+
+function scanLine (line, offset, matches, content) {
+  const inAttributeEntry = ATTRIBUTE_ENTRY_RX.test(line)
+  for (const match of line.matchAll(URL_RX)) {
+    const [, linkPrefix, rawUrl, rawLabel] = match
+    const backticksBefore = (line.slice(0, match.index).match(/`/g) || []).length
+    if (backticksBefore % 2 === 1) continue
+    const prefixLength = linkPrefix ? linkPrefix.length : 0
+    const start = offset + match.index
+    let url = rawUrl
+    let label = rawLabel ? rawLabel.slice(1, -1) : null
+    let end = start + prefixLength + url.length + (rawLabel ? rawLabel.length : 0)
+    if (!rawLabel) {
+      const wrapped = readWrappedLabel(content, start + prefixLength + url.length)
+      if (wrapped) {
+        label = wrapped.label
+        end = wrapped.end
+      } else {
+        url = url.replace(TRAILING_PUNCT_RX, '')
+        end = start + prefixLength + url.length
+      }
+    }
+    // A URL directly after an attribute assignment (link=, window=, ...) is a
+    // macro attribute value, not a standalone link.
+    const before = line.slice(0, match.index)
+    matches.push({
+      url,
+      label,
+      start,
+      end,
+      hasLinkPrefix: Boolean(linkPrefix),
+      inAttributeEntry,
+      inAttributeValue: /[\w-]=["']?$/.test(before),
+    })
+  }
+}
+
+module.exports = { scanContentUrls }

package/extensions/validate-attributes.js

@@ -68,7 +68,7 @@ function validateCategories(pageCategoryList, pageInfo, categoryMap, logger) {
   });
 
   if (!isValid) {
-      logger.warn(`Invalid categories detected. For a list of valid categories, see https://github.com/redpanda-data/docs/tree/shared/modules/ROOT/partials/valid-categories.yml`);
+      logger.warn(`Invalid categories detected. For a list of valid categories, see https://github.com/redpanda-data/docs/blob/main/shared/modules/ROOT/partials/valid-categories.yml`);
   }
   return Array.from(adjustedCategories).join(', ');
 }

package/macros/PROPERTY_AND_ENTERPRISE_REFERENCES.adoc

@@ -0,0 +1,90 @@
+= How property and enterprise references work
+:toc:
+:toclevels: 2
+
+A plain-English explanation of how the docs mark configuration properties and enterprise features, why it works this way, and what the tooling does for you. For attribute-by-attribute details, see link:REFERENCE.adoc[the macros reference].
+
+== The problem this solves
+
+The docs used to *guess*. Property tooltips decorated every piece of inline code whose text happened to match a property name. That works fine for a name like `cloud_storage_enabled`, but five real property names are ordinary words: `admin`, `brokers`, `rack`, `retries`, and `superusers`. On a Helm chart page, `admin` usually means an audit-logging setting or a listener name -- and readers still got a tooltip describing the Admin API broker property. Wrong information, delivered confidently.
+
+Enterprise feature mentions had the opposite problem: nothing checked them at all. Any writer could mark any feature as enterprise, under any name, and nothing would ever notice a typo, a made-up name, or a feature that isn't actually enterprise.
+
+The fix for both is the same idea: *marking is explicit, and every mark is checked against a source of truth at build time.*
+
+== Property references: the prop macro
+
+To reference a configuration property in prose, write:
+
+[,asciidoc]
+----
+prop:cloud_storage_enabled[]
+----
+
+That's it. Here's what happens for you:
+
+*It's checked.* The name is looked up in the published property data -- the same JSON, generated from Redpanda's source code, that powers the reference pages and tooltips. A typo gets a build warning with the file name and a "did you mean" suggestion. Nothing unverified ships. (A site can turn this up to a hard build failure with the `property-validate` attribute.)
+
+*It gets a tooltip.* The docs UI decorates only elements the macro marked. A plain backticked word never gets a tooltip anymore, so `admin` in a Helm example stays plain text unless a writer deliberately writes `prop:admin[]`.
+
+*It can link itself.* Add `link=true` and the property links to its reference page. You don't say which page -- the build works that out by looking at which reference page actually documents that property (details below). If our property reference is ever reorganized into different pages, every link follows automatically.
+
+*It adapts to Kubernetes pages.* Add `helm-path=auto` and, on pages rendered for Kubernetes, the property displays as the Helm values path readers actually type -- `config.cluster.log_segment_size`, `config.node.fips_mode`, or `storage.tiered.config.cloud_storage_enabled` for tiered storage settings. On Linux pages the same call shows the plain name. One sentence, correct for both audiences.
+
+*Once per paragraph is enough.* Mark the first mention of a property in a paragraph and leave later mentions as plain backticks -- a paragraph doesn't need three identical tooltips. The migration tool follows this rule, and the UI enforces it as a backstop: even if every mention is marked, only the first one per paragraph gets the tooltip.
+
+=== How "the build works out the page" (dynamic discovery)
+
+Rather than hardcoding "cluster properties live on the cluster-properties page," the macro reads the actual docs during the build. Every documented property appears as a heading in the generated property files, and each reference page pulls in one or more of those files. The macro follows that chain -- which pages exist, what they include, which property headings end up where -- and builds a lookup table per doc set.
+
+Because the lookup is done separately for each part of the site, a Cloud page links to Cloud's own property pages and a streaming page to streaming's. Cloud reuses streaming's property files with a filter ("only the cloud-relevant parts"), and the macro applies that same filter, so it never links to a property that a given page doesn't actually document. If a doc set doesn't cover a property at all -- Cloud publishes no topic-properties page, Connect publishes none -- the link borrows the streaming docs instead of pointing nowhere.
+
+Think phone book, not memory: if a property moves, the next build's phone book is already right.
+
+=== What happened to config_ref
+
+The old `config_ref` macro did a smaller version of this job with three problems: you had to tell it which page to link to by hand, it never checked the property name, and on Kubernetes pages it prefixed *every* property with `storage.tiered.config.` -- which is only correct for tiered storage settings. The live docs really did render `storage.tiered.config.log_segment_size`, a path that mislabels where that setting belongs.
+
+`config_ref` is deprecated. Every hand-written call site has been converted, the property extractor now emits `prop` in generated content, and the published JSON was cleaned up (it had been leaking raw macro text into tooltips). The macro stays registered only because older versioned docs, which are frozen, still contain it. Don't write it in new content.
+
+=== Migrating existing content
+
+One command converts a repo's prose:
+
+[,bash]
+----
+npx doc-tools generate migrate-property-refs \
+  --properties modules/reference/attachments/redpanda-properties-<tag>.json \
+  --config-refs
+----
+
+It's a dry run by default; add `--write` to apply. It only converts names it can verify in the published JSON, never touches the five ambiguous word-like names, and skips code blocks, headings, generated content, and anything already inside another macro.
+
+One thing no tool can check: *meaning*. Marking a name asserts "this mention refers to the Redpanda property" -- and even distinctive names collide in foreign-vocabulary contexts. A Terraform provider table's `replication.factor` argument, a SQL statement's `cluster_id` parameter, or an infrastructure checklist's `cloud_storage_bucket` are other systems' identifiers that happen to share a spelling. When reviewing a migration, unmark those. When writing, only reach for `prop:` when a tooltip describing the Redpanda property would help the reader in that sentence.
+
+== Enterprise feature references: the enterprise macro
+
+The same explicit-and-checked idea, for licensing:
+
+[,asciidoc]
+----
+enterprise:Tiered Storage[]
+----
+
+The name is validated against the *enterprise features registry* -- a single YAML file in the shared component (`shared/modules/ROOT/partials/enterprise-features.yml` in the docs repo) that is the canonical list of what is enterprise and what each feature is called externally. Writers can't misname a feature (aliases and case differences resolve to the canonical name, and internal engineering names like `cloud_storage` render as their proper external name) and can't mark something enterprise that isn't in the registry. Adding a feature to the registry is a reviewed docs change, and each entry records *why* it's enterprise by pointing at the internal source of truth (a license-gate in Redpanda's source, the Connect plugin catalog, or a written justification).
+
+Two more things come from the same registry:
+
+* The licensing feature tables on the licensing pages are *generated* from it (`enterprise_features::redpanda[]` and friends), so the tables can never disagree with the registry.
+* `doc-tools validate enterprise-features` compares the registry against the actual license gates in Redpanda's source code and Connect's plugin list. When engineering ships a new license-gated feature, CI fails until someone decides its documented name -- naming stays a human decision, but forgetting is no longer possible.
+
+Like properties, feature links adapt to context: registry entries can carry Kubernetes- and Cloud-specific pages, chosen by the page's environment attributes.
+
+== Where to see all of this working
+
+* The extensions preview site's test page demonstrates every form of both macros, including intentional failure cases, and a Kubernetes-environment page shows the environment-specific behavior side by side.
+* The docs-ui preview's `property-tooltips-test` and `enterprise-macro-test` pages show every output shape the UI styles, including the negative cases (unmarked names must get nothing).
+
+== The one-sentence version
+
+Nothing in the docs claims a name is a property or a feature is enterprise unless a writer said so explicitly *and* the build verified it against the source of truth.

package/macros/README.adoc

@@ -10,6 +10,8 @@ AsciiDoc macros are custom inline and block elements that extend AsciiDoc syntax
 
 == Documentation
 
+link:PROPERTY_AND_ENTERPRISE_REFERENCES.adoc[**How property and enterprise references work**]:: Plain-English explanation of the prop and enterprise macros: explicit marking, build-time validation against sources of truth, dynamic link discovery, and why config_ref was deprecated
+
 link:USER_GUIDE.adoc[**User guide**]:: How to use AsciiDoc macros in your documentation
 +
 * Installation and setup

package/macros/REFERENCE.adoc

@@ -20,6 +20,8 @@ antora:
 
 == config_ref
 
+IMPORTANT: `config_ref` is deprecated. The <<prop>> macro supersedes all of its functionality: it validates names against the published property reference, discovers the target page dynamically instead of taking a manual path, powers hover tooltips, and its `helm-path=auto` attribute replaces `config_ref`'s Kubernetes prefixing with a per-property correct Helm values path (`config_ref` prefixed every property with `storage.tiered.config.`, mislabeling non-tiered properties). Migrate call sites with `doc-tools generate migrate-property-refs --config-refs`. The macro stays registered only because the generated property partials still emit it.
+
 This inline macro is used to generate a reference to a configuration value in the Redpanda documentation. The macro's parameters allow for control over the generated reference's format and the type of output produced.
 
 === Usage
@@ -62,6 +64,171 @@ asciidoc:
     - '@redpanda-data/docs-extensions-and-macros/macros/config-ref'
 ----
 
+== enterprise
+
+This inline macro marks a feature as an enterprise feature in prose. The feature name renders as a uniquely styled term with a tooltip explaining that the feature requires an Enterprise Edition license, and links to the feature's documentation or to the licensing page.
+
+The macro validates its target against the enterprise features registry: `modules/ROOT/partials/enterprise-features.yml` in the `shared` component (the `shared/` folder of the docs repository). The registry is the canonical list of enterprise features and their approved external names. Targets are matched case-insensitively, including aliases, and the canonical name, feature page link, and tooltip come from the matching entry. A target that matches no entry is reported according to `enterprise-validate`. To mark a new feature as enterprise, add it to the registry first.
+
+=== Usage
+
+[,asciidoc]
+----
+enterprise:Continuous Data Balancing[]
+enterprise:Tiered Storage[xref=manage:tiered-storage.adoc]
+enterprise:Audit Logging[text=audit logging]
+enterprise:Iceberg Topics[tooltip=Iceberg Topics requires an Enterprise Edition license and object storage.]
+----
+
+The macro target is the feature name, which can contain spaces. Named attributes:
+
+xref::
+Optional Antora resource ID of the feature's documentation page. Overrides the registry entry's link. When neither is set, the term links to the licensing page.
++
+Registry entries can carry environment-specific pages: on pages with the `env-cloud` attribute the entry's `xref-cloud` is used, on pages with `env-kubernetes` the entry's `xref-kubernetes` is used, and otherwise the entry's default `xref` (the Linux or generic self-managed page). This mirrors the `config_ref` macro's environment awareness.
+
+text::
+Optional display text override. Use it when the sentence needs different casing or phrasing than the feature name.
+
+tooltip::
+Optional tooltip text override. Overrides the registry entry's `tooltip`. The default is `<feature> requires an Enterprise Edition license.`
+
+=== Configuration options
+
+enterprise-validate::
+How to report a target that does not match any registry entry: `warn` (default) logs a build warning with the file path and close-match suggestions, `error` fails the build, and `off` disables validation. When no registry is available in the build, the macro renders without validation and logs a single warning.
+
+enterprise-licensing-page::
+Resource ID of the licensing page used when no `xref` attribute is given. The default is `get-started:licensing/overview.adoc`.
+
+enterprise-feature-role::
+CSS class applied to the wrapping span. The default is `enterprise-feature`. Style this class in the UI bundle to give enterprise terms a consistent visual treatment.
+
+enterprise-tooltip::
+Controls the tooltip attribute: `title` (default), `true` (renders `data-enterprise-tooltip` for UI-driven tooltips), any attribute name starting with `data-`, or `false` to disable tooltips.
+
+enterprise-links::
+Set to `false` to render the term without a link.
+
+enterprise-beta-badge::
+Set to `false` to suppress the beta badge in prose. Generated tables always show it. See <<beta-features>>.
+
+[[beta-features]]
+=== Beta features
+
+Add `beta: true` to a registry entry to mark the feature as beta. The macro then renders a beta badge after the feature name, both in prose and in the generated `enterprise_features` tables, so one registry field keeps every reference consistent:
+
+[,yaml]
+----
+- name: Stretch Clusters
+  scope: operator
+  beta: true
+  feature-suffix: (StretchCluster resource)
+----
+
+Add `beta-tooltip` to give the badge hover text.
+
+Do not write a `badge:` macro call into `feature-suffix` to achieve this. The badge is emitted as an inline passthrough, so it renders whether or not the consuming playbook registers the `badge` macro, and it degrades to the text `(beta)` in Markdown. A hand-written macro call renders as literal source text in any build that does not register that macro.
+
+=== Markdown output
+
+In HTML, the enterprise signal is carried by the span's CSS class and its tooltip attribute. Both are attributes, so an HTML-to-Markdown conversion drops them and the term arrives as an ordinary feature name. To keep the signal for readers of the Markdown pages, including AI agents, the `convert-to-markdown` extension appends an explicit `(enterprise)` marker and preserves any link:
+
+[,markdown]
+----
+Enable [Tiered Storage](../manage/tiered-storage.md) (enterprise) today.
+----
+
+A feature that is also marked `beta: true` gets one combined marker rather than two adjacent parentheticals:
+
+[,markdown]
+----
+Enable [Stretch Clusters](../deploy/stretch-clusters.md) (enterprise, beta) today.
+----
+
+This applies to the inline macro. The tables from `enterprise_features` need no enterprise marker, because their expiration column already states the licensing behavior as text. A beta badge in a table converts to `(beta)` on its own.
+
+=== Registration
+
+[,yaml]
+----
+asciidoc:
+  extensions:
+    - '@redpanda-data/docs-extensions-and-macros/macros/enterprise'
+----
+
+== enterprise_features
+
+This block macro renders the licensing feature table for one scope from the enterprise features registry (see <<enterprise>>). Because the table is generated, it can never drift from the registry.
+
+=== Usage
+
+[,asciidoc]
+----
+enterprise_features::redpanda[]
+enterprise_features::connect[]
+enterprise_features::operator[title=Operator features,heading=What stops working]
+----
+
+The target is the scope: `redpanda`, `console`, `connect`, `operator`, or `cloud`. Rows render alphabetically by feature name with three columns: the feature name (linked to its documentation page when the entry has an `xref` or `url`), the description, and the expiration or restriction behavior. Named attributes:
+
+title::
+Optional table title override. The default is scope-specific, for example `Enterprise features in Redpanda`.
+
+heading::
+Optional third-column heading override. The default is `Behavior Upon Expiration` for the `redpanda` scope and `Restrictions Without Valid License` for the other scopes.
+
+=== Registration
+
+Registered together with the `enterprise` inline macro (see <<enterprise>>).
+
+== prop
+
+This inline macro references a Redpanda configuration property in prose. The property renders as a marked `<code>` element (`property-ref` class plus a `data-property-name` attribute) that the docs UI decorates with a hover-documentation tooltip. Marking is opt-in: only properties referenced through this macro get tooltips, so ambiguous words such as `admin` or `rack` in unrelated contexts (Helm values, feature settings) are never decorated by mistake.
+
+The macro validates its target against the published property reference: the newest `redpanda-properties-<tag>.json` attachment in the `reference` module of the build, the same data the tooltips fetch at runtime. To migrate existing plain-backtick property mentions, use `doc-tools generate migrate-property-refs`.
+
+=== Usage
+
+[,asciidoc]
+----
+prop:cloud_storage_enabled[]
+prop:iceberg_enabled[link=true]
+prop:retention_ms[link=true,page=properties/topic-properties]
+prop:write_caching_default[text=write caching]
+----
+
+The macro target is the property name. Named attributes:
+
+link::
+Set to `true` to also link the property to its reference page. The page is discovered dynamically: the macro indexes which reference-module page in the current component documents each property, by scanning property headings in the partials each page includes (respecting include tag filters such as `tags=redpanda-cloud`). Links are component-relative, so a Cloud page links to the Cloud component's own property pages, and they keep working if properties are split across different pages in the future. When discovery finds nothing, the page falls back deterministically to the property's `config_scope` (`cluster`, `broker`, or `topic`). This supersedes the `config_ref` macro's linking for most uses.
+
+page::
+Optional reference-page override (module-relative, without `.adoc`), for example `properties/object-storage-properties`. Overrides discovery entirely.
+
+helm-path::
+Set to `auto` to display the property as its Helm values path on pages rendered with the `env-kubernetes` attribute, so single-sourced content reads correctly for both Linux and Kubernetes audiences. The path is derived per property: `storage.tiered.config.<name>` for tiered storage properties, `config.node.<name>` for broker properties, and `config.cluster.<name>` for other cluster properties. On pages without `env-kubernetes`, the plain property name renders. This supersedes the deprecated `config_ref` macro's prefixing.
+
+text::
+Optional display text override. Wins over the Helm path display.
+
+=== Configuration options
+
+property-validate::
+How to report a target that does not match any published property: `warn` (default) logs a build warning with the file path and close-match suggestions, `error` fails the build, and `off` disables validation. When no property JSON is available in the build, the macro renders without validation and logs a single warning.
+
+property-ref-role::
+CSS class applied to the code element. The default is `property-ref`.
+
+=== Registration
+
+[,yaml]
+----
+asciidoc:
+  extensions:
+    - '@redpanda-data/docs-extensions-and-macros/macros/prop'
+----
+
 == glossterm
 
 The `glossterm` inline macro provides a way to define and reference glossary terms in your AsciiDoc documents.

package/macros/badge.js

@@ -1,21 +1,43 @@
 'use strict';
 
+/**
+ * Build the HTML for a badge.
+ *
+ * Extracted from the macro body so other macros can render an identical badge
+ * without depending on the badge macro being registered in the consuming
+ * playbook. The enterprise macro uses it to render the beta badge for registry
+ * entries marked `beta: true`, which keeps one definition of the markup and
+ * the CSS class names.
+ *
+ * @param {object} opts
+ * @param {string} [opts.label] - Badge text.
+ * @param {string} [opts.size] - `large` renders without surrounding brackets.
+ * @param {string} [opts.tooltip] - Tooltip text, rendered as `data-tooltip`.
+ * @returns {string} Badge HTML.
+ */
+function buildBadgeHtml ({ label, size, tooltip } = {}) {
+  const text = label || 'label';
+  const className = `badge--${text.toLowerCase().replace(/\s+/g, '-')}`;
+  const isLarge = size === 'large';
+  const sizeClass = isLarge ? 'badge--large' : '';
+  const tooltipAttr = tooltip ? ` data-tooltip="${tooltip}"` : '';
+
+  // Add brackets if not large. The brackets matter beyond styling: they are
+  // real text content, so the label survives an HTML-to-Markdown conversion as
+  // "(beta)" rather than vanishing with the CSS class.
+  const renderedLabel = isLarge ? text : `(${text})`;
+
+  return `<span class="badge ${className} ${sizeClass}"${tooltipAttr}>${renderedLabel}</span>`;
+}
+
+module.exports.buildBadgeHtml = buildBadgeHtml;
+
 module.exports.register = function (registry) {
   registry.inlineMacro(function () {
     const self = this;
     self.named('badge');
-    self.process((parent, target, attrs) => {
-      const label = attrs.label || 'label';
-      const className = `badge--${label.toLowerCase().replace(/\s+/g, '-')}`;
-      const isLarge = attrs.size === 'large';
-      const sizeClass = isLarge ? 'badge--large' : '';
-      const tooltip = attrs.tooltip;
-      const tooltipAttr = tooltip ? ` data-tooltip="${tooltip}"` : '';
-
-      // Add brackets if not large
-      const renderedLabel = isLarge ? label : `(${label})`;
-
-      return `<span class="badge ${className} ${sizeClass}"${tooltipAttr}>${renderedLabel}</span>`;
-    });
+    self.process((parent, target, attrs) =>
+      buildBadgeHtml({ label: attrs.label, size: attrs.size, tooltip: attrs.tooltip })
+    );
   });
 };