@redpanda-data/docs-extensions-and-macros 5.7.1 → 5.9.0

package/bin/doc-tools.js

@@ -827,6 +827,48 @@ automation
     migrateMetadataToPartials({ write: Boolean(options.write) })
   })
 
+/**
+ * @description One-time migration of plain-backtick property mentions to the
+ * prop: inline macro, so property tooltips become opt-in. Only names that
+ * exist in the published property reference JSON AND contain a separator
+ * (_ or .) are converted. Separator-free names such as admin, brokers, rack,
+ * retries, and superusers are the ambiguous words that motivated opt-in
+ * marking, so they are always left for a human. Dry run unless --write is given.
+ *
+ * @example
+ * # Preview the conversion from a docs repo checkout
+ * npx doc-tools generate migrate-property-refs --properties modules/reference/attachments/redpanda-properties-v26.2.1.json
+ *
+ * # Apply it
+ * npx doc-tools generate migrate-property-refs --properties modules/reference/attachments/redpanda-properties-v26.2.1.json --write
+ */
+automation
+  .command('migrate-property-refs')
+  .description('One-time migration of `property_name` prose mentions to prop:property_name[] macros. Dry run unless --write is given.')
+  .requiredOption('--properties <path>', 'Path to the published redpanda-properties JSON to validate names against')
+  .option('--docs-dir <path>', 'Docs repo root containing modules/', '.')
+  .option('--config-refs', 'Also convert config_ref macro calls to prop macro calls')
+  .option('--write', 'Apply changes (default is a dry run that only reports)')
+  .action((options) => {
+    const { migrate } = require('../tools/migrate-property-refs.js')
+    const propertiesJson = JSON.parse(fs.readFileSync(path.resolve(options.properties), 'utf8'))
+    const result = migrate({
+      docsDir: path.resolve(options.docsDir),
+      propertiesJson,
+      write: Boolean(options.write),
+      configRefs: Boolean(options.configRefs),
+    })
+    result.changed
+      .sort((a, b) => b.count - a.count)
+      .forEach(({ file, count }) => console.log(`${String(count).padStart(4)}  ${file}`))
+    console.log(`\n${options.write ? 'Converted' : 'Would convert'} ${result.conversions} mention(s) across ${result.changed.length} of ${result.files} files.`)
+    console.log(`Left alone (ambiguous, no separator): ${result.ambiguous.join(', ')}`)
+    if (result.skippedConfigRefs && result.skippedConfigRefs.length) {
+      console.log(`config_ref calls left alone (names not in the published JSON): ${result.skippedConfigRefs.join(', ')}`)
+    }
+    if (!options.write && result.conversions) console.log('Re-run with --write to apply.')
+  })
+
 /**
  * generate property-docs
  *
@@ -1660,6 +1702,21 @@ automation
             return match
           }
         })
+      // Antora resolves page metadata with a header-only parse that stops at
+      // the first blank line. The chart README templates emit :description:
+      // below the title's blank line, so the page shipped the generic site
+      // meta description despite carrying one (found on k-connect-helm-spec,
+      // DOC-2414 investigation). Relocate the first :description: into the
+      // header, directly under the title.
+      const descMatch = doc.match(/^:description:[^\n]*$/m)
+      if (descMatch) {
+        const headerEnd = doc.indexOf('\n\n')
+        if (headerEnd !== -1 && doc.indexOf(descMatch[0]) > headerEnd) {
+          doc = doc.replace(descMatch[0] + '\n', '')
+          doc = doc.replace(/^(= .+)$/m, `$1\n${descMatch[0]}`)
+          doc = doc.replace(/\n{3,}/g, '\n\n')
+        }
+      }
       fs.writeFileSync(outFile, doc, 'utf8')
 
       console.log(`Done: Wrote ${outFile}`)
@@ -2118,5 +2175,131 @@ automation
     }
   })
 
+const validation = new Command('validate').description('Validate docs data against internal sources of truth')
+
+/**
+ * @description Checks the enterprise features registry (the shared component's
+ * enterprise-features.yml in the docs repo) against the internal sources of
+ * truth: the license_required_feature enum and config::enterprise<> property
+ * wrappers in redpanda core, the enterprise plugins in connect info.csv, and
+ * the hand-maintained disable-enterprise-features.adoc table.
+ * Exit codes: 0 clean, 1 drift found (error or needs-human findings), 2 execution error.
+ *
+ * @why A feature must only be documented as enterprise under its approved
+ * external name. This check catches new license-gated features in core that
+ * have no registry entry yet, registry pointers that no longer match core,
+ * and stale connect enterprise lists.
+ *
+ * @example
+ * # Check everything against the default remote sources
+ * npx doc-tools validate enterprise-features
+ *
+ * # Check a local registry file (for example, in docs repo CI)
+ * npx doc-tools validate enterprise-features --registry shared/modules/ROOT/partials/enterprise-features.yml
+ *
+ * # Regenerate the rpk name-mapping partial
+ * npx doc-tools validate enterprise-features --write-mapping modules/get-started/partials/licensing/feature-name-mapping.adoc
+ *
+ * @requirements
+ * Network access to raw.githubusercontent.com for any source not supplied
+ * with a local path option.
+ */
+validation
+  .command('enterprise-features')
+  .description('Check the enterprise features registry against core, connect, and docs sources of truth')
+  .option('--registry <path>', 'Local path to enterprise-features.yml (default: fetch from docs repo main)')
+  .option('--tag <ref>', 'Redpanda git ref for the core headers', 'dev')
+  .option('--connect-ref <ref>', 'Connect git ref for info.csv', 'main')
+  .option('--docs-ref <ref>', 'Docs repo git ref for remote fetches', 'main')
+  .option('--disable-page <path>', 'Local path to disable-enterprise-features.adoc (default: fetch from docs repo)')
+  .option('--antora <path>', 'Local path to rp-connect-docs antora.yml (default: fetch from rp-connect-docs main)')
+  .option('--properties <path>', 'Local path to a generated cluster-properties JSON; enables existence checks for gating properties')
+  .option('--skip-connect', 'Skip the connect info.csv comparison')
+  .option('--format <format>', 'Output format: text or json', 'text')
+  .option('--write-mapping <path>', 'Write the internal-to-external name mapping partial to this path')
+  .action(async (options) => {
+    const { runChecks, buildMappingPartial } = require('../tools/enterprise-features/verify')
+    const { extractAntoraEnterpriseComponents } = require('../tools/enterprise-features/parsers')
+    const yamlLib = require('js-yaml')
+
+    const RAW = 'https://raw.githubusercontent.com'
+    // Sources that fail to load are reported as error-level findings rather
+    // than silently skipped, so CI cannot pass on a check that never ran.
+    const failedSources = []
+    async function fetchText (url, sourceName) {
+      const resp = await fetch(url)
+      if (!resp.ok) {
+        if (sourceName) {
+          failedSources.push({ level: 'error', check: 'fetch', message: `Could not load ${sourceName} (${url}): ${resp.status} ${resp.statusText}. The related checks did not run.` })
+          return undefined
+        }
+        throw new Error(`Failed to fetch ${url}: ${resp.status} ${resp.statusText}`)
+      }
+      return resp.text()
+    }
+    const readLocal = (p) => fs.readFileSync(path.resolve(p), 'utf8')
+
+    try {
+      const registryYaml = options.registry
+        ? readLocal(options.registry)
+        : await fetchText(`${RAW}/redpanda-data/docs/${options.docsRef}/shared/modules/ROOT/partials/enterprise-features.yml`)
+      const coreHeader = await fetchText(`${RAW}/redpanda-data/redpanda/${options.tag}/src/v/features/enterprise_features.h`, 'core enterprise_features.h')
+      const configurationHeader = await fetchText(`${RAW}/redpanda-data/redpanda/${options.tag}/src/v/config/configuration.h`, 'core configuration.h')
+      const infoCsv = options.skipConnect
+        ? undefined
+        : await fetchText(`${RAW}/redpanda-data/connect/${options.connectRef}/internal/plugins/info.csv`, 'connect info.csv')
+      const disablePage = options.disablePage
+        ? readLocal(options.disablePage)
+        : await fetchText(`${RAW}/redpanda-data/docs/${options.docsRef}/modules/get-started/pages/licensing/disable-enterprise-features.adoc`, 'disable-enterprise-features.adoc')
+      const antoraYaml = options.antora
+        ? readLocal(options.antora)
+        : await fetchText(`${RAW}/redpanda-data/rp-connect-docs/main/antora.yml`, 'rp-connect-docs antora.yml')
+      const antoraEnterpriseComponents = antoraYaml
+        ? extractAntoraEnterpriseComponents(yamlLib.load(antoraYaml))
+        : undefined
+
+      let allPropertyNames
+      if (options.properties) {
+        const propertyData = JSON.parse(readLocal(options.properties))
+        allPropertyNames = Object.keys(propertyData.properties || propertyData)
+      }
+
+      const { findings, features, enumValues } = runChecks({
+        registryYaml,
+        coreHeader,
+        configurationHeader,
+        infoCsv,
+        antoraEnterpriseComponents,
+        disablePage,
+        allPropertyNames,
+      })
+      findings.push(...failedSources)
+
+      if (options.writeMapping) {
+        const partial = buildMappingPartial(features, enumValues)
+        fs.mkdirSync(path.dirname(path.resolve(options.writeMapping)), { recursive: true })
+        fs.writeFileSync(path.resolve(options.writeMapping), `${partial}\n`)
+        console.log(`Wrote name mapping partial to ${options.writeMapping}`)
+      }
+
+      const drift = findings.filter((f) => f.level === 'error' || f.level === 'needs-human')
+      if (options.format === 'json') {
+        console.log(JSON.stringify({ findings, drift: drift.length > 0 }, null, 2))
+      } else {
+        for (const level of ['error', 'needs-human', 'info']) {
+          for (const f of findings.filter((entry) => entry.level === level)) {
+            console.log(`${level.toUpperCase()} [${f.check}] ${f.message}`)
+          }
+        }
+        console.log(drift.length ? `\n${drift.length} finding(s) need attention.` : '\nRegistry is in sync with all checked sources.')
+      }
+      process.exit(drift.length ? 1 : 0)
+    } catch (err) {
+      console.error(`Error: ${err.message}`)
+      process.exit(2)
+    }
+  })
+
 programCli.addCommand(automation)
+programCli.addCommand(validation)
 programCli.parse(process.argv)

package/extensions/convert-to-markdown.js

@@ -187,6 +187,116 @@ function generateFrontmatter(page) {
   return `---\n${yamlContent}---\n\n`
 }
 
+// Default class the enterprise inline macro puts on its wrapping span. The
+// macro lets a playbook override it via the enterprise-feature-role document
+// attribute, so match on a substring rather than the exact value.
+const ENTERPRISE_FEATURE_CLASS = 'enterprise-feature'
+
+// Status words collected into the single trailing parenthetical.
+const ENTERPRISE_STATUS = 'enterprise'
+const BETA_STATUS = 'beta'
+
+// Class the badge macro puts on a beta badge.
+const BETA_BADGE_CLASS = 'badge--beta'
+
+// Explicit textual marker for enterprise features in Markdown output.
+const ENTERPRISE_MARKER = `(${ENTERPRISE_STATUS})`
+
+/**
+ * Format one parenthetical from the status words that apply to a feature.
+ *
+ * A beta enterprise feature carries two markers, and emitting them separately
+ * reads as "Stretch Clusters (enterprise) (beta)". One list avoids the stutter.
+ *
+ * @param {string[]} statuses - Status words, in display order.
+ * @returns {string} Parenthetical, or an empty string when there are none.
+ */
+function formatStatusMarker (statuses) {
+  const words = statuses.filter(Boolean)
+  return words.length ? `(${words.join(', ')})` : ''
+}
+
+function hasClass (node, className) {
+  if (!node || node.nodeName !== 'SPAN') return false
+  const classAttr = node.getAttribute?.('class') || node.className || ''
+  return typeof classAttr === 'string' && classAttr.includes(className)
+}
+
+/**
+ * The next sibling element, skipping the whitespace text nodes that sit between
+ * the enterprise span and a badge that follows it.
+ */
+function nextElementSibling (node) {
+  let sibling = node && node.nextSibling
+  while (sibling && sibling.nodeType === 3 && !(sibling.textContent || '').trim()) {
+    sibling = sibling.nextSibling
+  }
+  return sibling && sibling.nodeType === 1 ? sibling : null
+}
+
+/**
+ * Turndown rules that keep the enterprise and beta signals in Markdown output.
+ *
+ * In HTML both signals are carried by things Turndown discards. The enterprise
+ * badge is drawn by CSS from the span's class and explained by a title tooltip,
+ * so `enterprise:Tiered Storage[]` would arrive in Markdown as the bare words
+ * "Tiered Storage", indistinguishable from any other feature name. The beta
+ * badge does survive, because its label keeps real bracketed text, but it lands
+ * as a second parenthetical right after the first.
+ *
+ * These rules emit one trailing parenthetical instead, listing every status
+ * that applies, and pass the span's already-converted inner Markdown through
+ * untouched so a linked feature keeps its link:
+ *
+ *   [Stretch Clusters](../deploy/stretch-clusters.md) (enterprise, beta)
+ *
+ * The beta badge is a sibling of the enterprise span rather than a child. The
+ * enterprise rule looks ahead for it and, when it finds one, emits no marker of
+ * its own and hands the combined marker to the badge. Emitting it there rather
+ * than on the enterprise span reuses the whitespace already between the two
+ * elements, instead of suppressing the badge and leaving a doubled space.
+ *
+ * @returns {{enterpriseFeature: object, betaBadge: object}} Turndown rules,
+ *   both of which must be registered.
+ */
+function createEnterpriseFeatureRules () {
+  // Scoped per call so each converter tracks its own deferred markers.
+  const deferredToBadge = new WeakSet()
+
+  const enterpriseFeature = {
+    filter: (node) => hasClass(node, ENTERPRISE_FEATURE_CLASS),
+    replacement: (content, node) => {
+      const inner = (content || '').trim()
+      // An empty span carries no feature to mark.
+      if (!inner) return ''
+      // Nested or already-marked content must not collect a second marker.
+      if (inner.toLowerCase().endsWith(ENTERPRISE_MARKER)) return inner
+
+      const sibling = nextElementSibling(node)
+      if (hasClass(sibling, BETA_BADGE_CLASS)) {
+        // The badge renders "(enterprise, beta)" for both of us.
+        deferredToBadge.add(sibling)
+        return inner
+      }
+      return `${inner} ${ENTERPRISE_MARKER}`
+    },
+  }
+
+  const betaBadge = {
+    filter: (node) => hasClass(node, BETA_BADGE_CLASS),
+    replacement: (content, node) =>
+      deferredToBadge.has(node)
+        ? formatStatusMarker([ENTERPRISE_STATUS, BETA_STATUS])
+        : formatStatusMarker([BETA_STATUS]),
+  }
+
+  return { enterpriseFeature, betaBadge }
+}
+
+module.exports.createEnterpriseFeatureRules = createEnterpriseFeatureRules
+module.exports.formatStatusMarker = formatStatusMarker
+module.exports.ENTERPRISE_MARKER = ENTERPRISE_MARKER
+
 module.exports.register = function () {
   raiseListenerLimit(this)
   const logger = this.getLogger('convert-to-markdown-extension')
@@ -406,6 +516,11 @@ module.exports.register = function () {
       })
 
       // Markdown table conversion
+      // Keep the enterprise-license signal, which is otherwise CSS-only.
+      const enterpriseRules = createEnterpriseFeatureRules()
+      turndownInstance.addRule('enterprise-feature', enterpriseRules.enterpriseFeature)
+      turndownInstance.addRule('beta-badge', enterpriseRules.betaBadge)
+
       turndownInstance.addRule('tables', {
         filter: (node) => {
           if (node.nodeName !== 'TABLE') return false

package/extensions/property-page-index.js

@@ -0,0 +1,44 @@
+'use strict'
+
+/* Antora extension that warms the prop macro's property-page index before
+ * document conversion starts.
+ *
+ * The prop macro discovers which reference page documents each property by
+ * reading page sources for include:: lines and partials for property
+ * headings. Antora replaces each page's contents with converted HTML as
+ * conversion proceeds, so an index built lazily by the first macro call can
+ * miss includes on pages that were converted earlier — the result silently
+ * depends on conversion order. Building the index at contentClassified,
+ * while every page still holds its AsciiDoc source, removes the ordering
+ * hazard entirely. The macro finds the warmed cache and never rebuilds it.
+ *
+ * Register under antora.extensions (NOT asciidoc.extensions):
+ *
+ *   antora:
+ *     extensions:
+ *     - require: '@redpanda-data/docs-extensions-and-macros/extensions/property-page-index'
+ */
+
+const { buildPageIndex, loadPropertiesFor } = require('../macros/prop')
+const { raiseListenerLimit } = require('./util/raise-listener-limit')
+
+module.exports.register = function () {
+  raiseListenerLimit(this)
+  const logger = this.getLogger('property-page-index-extension')
+
+  this.once('contentClassified', ({ contentCatalog }) => {
+    let indexed = 0
+    for (const component of contentCatalog.getComponents()) {
+      for (const componentVersion of component.versions) {
+        const registry = loadPropertiesFor(contentCatalog, component.name, componentVersion.version)
+        if (!registry) continue
+        const index = buildPageIndex(contentCatalog, component.name, registry.properties, componentVersion.version)
+        if (index.size > 0) {
+          indexed++
+          logger.debug(`Indexed ${index.size} properties for ${component.name}@${componentVersion.version || 'default'}`)
+        }
+      }
+    }
+    if (indexed > 0) logger.info(`Property page index warmed for ${indexed} component version(s)`)
+  })
+}

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