@redpanda-data/docs-extensions-and-macros 5.57.0 → 5.58.0

package/bin/doc-tools.js

@@ -1136,6 +1136,73 @@ automation
     if (!options.write && result.conversions) console.log('Re-run with --write to apply.')
   })
 
+/**
+ * @description Report hand-written property values in prose ("defaults to
+ * 128 MiB", "the minimum is 1 minute") next to a property mention, check each
+ * against the property data for the repo's own version (selected exactly as
+ * the prop: macro selects it), and propose a propval: replacement. Mismatches
+ * are likely doc errors. Also reads example command output in listing
+ * blocks (rpk topic describe, rpk cluster config get and export, Admin API
+ * cluster_config, kafka-configs --describe, Key/Value/Source records) and
+ * reports a row that asserts the default, such as SOURCE DEFAULT_CONFIG, but
+ * shows another value as stale example output, listed apart from prose
+ * findings. Dry run by default, writing a JSON and a Markdown report; --write
+ * applies only exact matches stated in the same sentence as their property,
+ * never a mismatch, a table cell or example output. Skips prose inside code
+ * blocks and generated content.
+ *
+ * @example
+ * # Report on a docs checkout
+ * npx doc-tools generate migrate-property-values --docs-dir . --report-dir ./propval-report
+ *
+ * # Report on cloud-docs, which borrows the self-managed docs' property data
+ * npx doc-tools generate migrate-property-values --docs-dir ../cloud-docs --lender ../docs
+ *
+ * # Apply the auto-safe exact matches
+ * npx doc-tools generate migrate-property-values --docs-dir . --write
+ */
+automation
+  .command('migrate-property-values')
+  .description('Report hand-written property values in prose and in example command output, check them against the property data, and propose propval: macros. Dry run unless --write is given; --write applies exact same-sentence prose matches only, never example output.')
+  .option('--docs-dir <path>', 'Docs repo root containing antora.yml and modules/', '.')
+  .option('--lender <path...>', 'Other component checkouts whose property data the repo borrows (cloud-docs borrows the docs repo\'s)')
+  .option('--report-dir <path>', 'Where to write property-values-report.json and property-values-report.md', '.')
+  .option('--write', 'Replace exact, same-sentence matches with propval: macros (mismatches are never rewritten)')
+  .action((options) => {
+    const { scanRepo, renderMarkdown } = require('../tools/migrate-property-values.js')
+    const result = scanRepo({
+      docsDir: path.resolve(options.docsDir),
+      lenderDirs: (options.lender || []).map((dir) => path.resolve(dir)),
+      write: Boolean(options.write),
+    })
+    if (result.error) {
+      console.error(`Error: ${result.error}`)
+      process.exit(1)
+    }
+    result.label = `${result.component}@${result.version || 'unversioned'}`
+    const reportDir = path.resolve(options.reportDir)
+    fs.mkdirSync(reportDir, { recursive: true })
+    fs.writeFileSync(path.join(reportDir, 'property-values-report.json'), JSON.stringify(result, null, 2) + '\n')
+    fs.writeFileSync(path.join(reportDir, 'property-values-report.md'), renderMarkdown([result]))
+    const { counts } = result
+    console.log(`Checked against ${result.dataset} (${result.surface}).`)
+    console.log(`${result.findings.length} value statement(s) in ${result.files} files: ${counts.mismatch} mismatch, ${counts.unset} unset, ${counts.exact} exact (${counts.autoSafe} auto-safe), ${counts.equivalent} equivalent, ${counts.unverifiable} unverifiable.`)
+    for (const f of result.findings.filter((x) => x.status === 'mismatch')) {
+      console.log(`  MISMATCH ${f.file}:${f.line} ${f.property} ${f.field}: written ${f.written}, data ${f.dataValue}`)
+    }
+    for (const f of result.findings.filter((x) => x.status === 'unset')) {
+      console.log(`  UNSET ${f.file}:${f.line} ${f.property} ${f.field}: ${f.note}`)
+    }
+    const examples = result.findings.filter((x) => x.status === 'example-output')
+    console.log(`${examples.length} value(s) in example output: ${counts.exampleStale} stale, ${examples.filter((x) => x.verdict === 'matches').length} matching, ${examples.filter((x) => x.verdict === 'unverifiable').length} unverifiable (never written).`)
+    for (const f of examples.filter((x) => x.verdict === 'stale')) {
+      console.log(`  EXAMPLE ${f.file}:${f.line} ${f.property}${f.clusterProperty ? ` (${f.clusterProperty})` : ''}: shown ${f.written}${f.source ? ` ${f.source}` : ''}, default ${f.dataRaw || f.dataValue}`)
+    }
+    if (options.write) console.log(`Replaced auto-safe exact matches in ${result.changedFiles} file(s).`)
+    else if (counts.autoSafe) console.log('Re-run with --write to replace the auto-safe exact matches.')
+    console.log(`Report: ${path.join(reportDir, 'property-values-report.md')}`)
+  })
+
 /**
  * generate property-docs
  *

package/extension-utils/property-values.js

@@ -0,0 +1,255 @@
+'use strict'
+
+/* Field values for one entry of a published redpanda-properties-<tag>.json,
+ * formatted the way the generated property reference renders them.
+ *
+ * Shared by the propval: inline macro (macros/prop.js) and the
+ * migrate-property-values report, so prose, the migration report, and the
+ * reference tables agree. The value strings come from the reference
+ * generator's own helpers wherever the tables show the field:
+ *
+ *   default   formatPropertyValue (the table's code value), and the
+ *             extractor's default_human_readable where the data carries it
+ *             (the table's parenthetical, such as "2 weeks").
+ *   unit      the table's Unit row: the units field, else formatUnits(name).
+ *
+ * Two humanizations go beyond what the table prints, and both are derived
+ * only from data the table also shows, never guessed:
+ *
+ *   Durations without default_human_readable use humanizeDuration, a port of
+ *   the extractor's format_time_human_readable (the function that produced
+ *   default_human_readable), so the wording is identical.
+ *   Byte values use IEC units (128 MiB) only when the table's Unit row says
+ *   bytes and the value is an exact multiple. Anything else renders exactly.
+ */
+
+const formatPropertyValue = require('../tools/property-extractor/helpers/formatPropertyValue')
+const formatUnits = require('../tools/property-extractor/helpers/formatUnits')
+const { escapeHtml } = require('./html-utils')
+
+const FORMAT_HUMAN = 'human'
+const FORMAT_RAW = 'raw'
+
+// Every field propval: supports. `cloudHidden` marks the fields the reference
+// pages wrap in ifndef::env-cloud[], so a Cloud page never states them either.
+const FIELDS = {
+  default: { cloudHidden: true },
+  type: {},
+  unit: {},
+  min: {},
+  max: {},
+  restart: {},
+  nullable: {},
+  values: {},
+  scope: {},
+  introduced: { cloudHidden: true },
+  visibility: { cloudHidden: true },
+  restored: { cloudHidden: true },
+  aliases: { cloudHidden: true },
+  'cloud-access': {},
+}
+
+// The JSON key names and table labels are accepted as aliases, so a writer
+// who types what they see in the data or on the page gets the same field.
+const FIELD_ALIASES = {
+  minimum: 'min',
+  maximum: 'max',
+  needs_restart: 'restart',
+  'requires-restart': 'restart',
+  units: 'unit',
+  enum: 'values',
+  'accepted-values': 'values',
+  config_scope: 'scope',
+  version: 'introduced',
+  gets_restored: 'restored',
+  cloud: 'cloud-access',
+}
+
+const DURATION_UNITS = { milliseconds: 1, seconds: 1000 }
+
+/**
+ * Canonical field name, or undefined for a field propval: does not support.
+ */
+function normalizeField (field) {
+  const key = String(field == null ? '' : field).trim().toLowerCase()
+  if (Object.prototype.hasOwnProperty.call(FIELDS, key)) return key
+  if (Object.prototype.hasOwnProperty.call(FIELD_ALIASES, key)) return FIELD_ALIASES[key]
+  return undefined
+}
+
+/**
+ * The unit the reference table prints for a property, lowercased for prose:
+ * the units field, else the one formatUnits derives from the name suffix.
+ * Empty when the table prints no Unit row.
+ */
+function unitOf (entry) {
+  if (entry && typeof entry.units === 'string' && entry.units.trim()) return entry.units.trim()
+  return formatUnits(entry && entry.name) || ''
+}
+
+/**
+ * Port of property_extractor.py's format_time_human_readable: the largest
+ * unit that divides the value evenly, else the value in its own unit.
+ *
+ * @param {number} value
+ * @param {'milliseconds'|'seconds'} unit
+ */
+function humanizeDuration (value, unit) {
+  const ms = unit === 'seconds' ? value * 1000 : value
+  const units = [
+    [365 * 24 * 60 * 60 * 1000, 'year', 'years'],
+    [7 * 24 * 60 * 60 * 1000, 'week', 'weeks'],
+    [24 * 60 * 60 * 1000, 'day', 'days'],
+    [60 * 60 * 1000, 'hour', 'hours'],
+    [60 * 1000, 'minute', 'minutes'],
+    [1000, 'second', 'seconds'],
+    [1, 'millisecond', 'milliseconds'],
+  ]
+  for (const [threshold, singular, plural] of units) {
+    if (ms >= threshold && ms % threshold === 0) {
+      const count = ms / threshold
+      return `${count} ${count === 1 ? singular : plural}`
+    }
+  }
+  return unit === 'seconds' ? `${value} seconds` : `${value} milliseconds`
+}
+
+/**
+ * IEC rendering of a byte count, only for exact multiples: 134217728 is
+ * "128 MiB", 1000 stays "1000 bytes".
+ */
+function humanizeBytes (value) {
+  if (value === 0) return '0 bytes'
+  const steps = [
+    [1024 ** 4, 'TiB'],
+    [1024 ** 3, 'GiB'],
+    [1024 ** 2, 'MiB'],
+    [1024, 'KiB'],
+  ]
+  for (const [size, label] of steps) {
+    if (value >= size && value % size === 0) return `${value / size} ${label}`
+  }
+  return `${value} ${value === 1 ? 'byte' : 'bytes'}`
+}
+
+/**
+ * A number in the property's own unit, humanized when the unit is known and
+ * the value is a non-negative integer. Negative values are sentinels (-1 for
+ * "unlimited") and render as written.
+ */
+function humanizeNumber (value, unit) {
+  if (typeof value !== 'number' || !Number.isInteger(value) || value < 0) return String(value)
+  if (DURATION_UNITS[unit]) return humanizeDuration(value, unit)
+  if (unit === 'bytes') return humanizeBytes(value)
+  return String(value)
+}
+
+// An integer outside JavaScript's exact range (2^64 - 1 sentinels such as
+// virtual_cluster_min_producer_ids) has already lost digits by the time
+// JSON.parse returns it, so there is no exact value left to render.
+const isImprecise = (value) => typeof value === 'number' && Number.isInteger(value) && !Number.isSafeInteger(value)
+const imprecise = () => ({ ok: false, reason: 'imprecise' })
+const plain = (text) => ({ ok: true, text: String(text) })
+const missing = () => ({ ok: false, reason: 'missing' })
+const yesNo = (value, format) => plain(format === FORMAT_RAW ? String(value) : (value ? 'yes' : 'no'))
+
+/**
+ * The value of one field of one property entry.
+ *
+ * @param {object} entry - One value of the JSON's properties object.
+ * @param {string} field - A field name or alias.
+ * @param {object} [opts]
+ * @param {'human'|'raw'} [opts.format] - human (default) or the exact value.
+ * @returns {{ok: true, text: string, html?: string} |
+ *           {ok: false, reason: 'unsupported'|'missing'|'imprecise'}}
+ *   html, when present, is pre-escaped markup to use instead of text.
+ */
+function fieldValue (entry, field, { format = FORMAT_HUMAN } = {}) {
+  const name = normalizeField(field)
+  if (!name) return { ok: false, reason: 'unsupported' }
+  const has = (key) => Object.prototype.hasOwnProperty.call(entry, key) && entry[key] !== undefined
+  const raw = format === FORMAT_RAW
+
+  switch (name) {
+    case 'default': {
+      if (!has('default')) return missing()
+      const value = entry.default
+      if (isImprecise(value)) return imprecise()
+      const exact = String(formatPropertyValue(value, entry.type))
+      if (raw) return plain(exact)
+      if (typeof entry.default_human_readable === 'string' && entry.default_human_readable.trim()) {
+        return plain(entry.default_human_readable.trim())
+      }
+      if (typeof value === 'number') return plain(humanizeNumber(value, unitOf(entry)))
+      return plain(exact)
+    }
+    case 'type':
+      return has('type') && entry.type !== '' ? plain(entry.type) : missing()
+    case 'unit': {
+      const unit = unitOf(entry)
+      return unit ? plain(unit) : missing()
+    }
+    case 'min':
+    case 'max': {
+      const key = name === 'min' ? 'minimum' : 'maximum'
+      if (!has(key) || entry[key] === null) return missing()
+      if (isImprecise(entry[key])) return imprecise()
+      return plain(raw ? String(entry[key]) : humanizeNumber(entry[key], unitOf(entry)))
+    }
+    case 'restart':
+      return has('needs_restart') && typeof entry.needs_restart === 'boolean' ? yesNo(entry.needs_restart, format) : missing()
+    case 'nullable':
+      return has('nullable') && typeof entry.nullable === 'boolean' ? yesNo(entry.nullable, format) : missing()
+    case 'restored':
+      return has('gets_restored') && typeof entry.gets_restored === 'boolean' ? yesNo(entry.gets_restored, format) : missing()
+    case 'values': {
+      const list = Array.isArray(entry.enum) && entry.enum.length
+        ? entry.enum
+        : entry.items && Array.isArray(entry.items.enum) && entry.items.enum.length ? entry.items.enum : undefined
+      if (!list) return missing()
+      if (raw) return plain(JSON.stringify(list))
+      // Each value in its own code element, as the table prints them: some
+      // values contain commas (compact,delete), so a plain comma-joined list
+      // would be ambiguous.
+      return {
+        ok: true,
+        text: list.map(String).join(', '),
+        html: list.map((v) => `<code>${escapeHtml(String(v))}</code>`).join(', '),
+      }
+    }
+    case 'scope':
+      return has('config_scope') && entry.config_scope ? plain(entry.config_scope) : missing()
+    case 'introduced':
+      return has('version') && entry.version ? plain(entry.version) : missing()
+    case 'visibility':
+      return has('visibility') && entry.visibility ? plain(entry.visibility) : missing()
+    case 'aliases':
+      return Array.isArray(entry.aliases) && entry.aliases.length
+        ? plain(raw ? JSON.stringify(entry.aliases) : entry.aliases.join(', '))
+        : missing()
+    case 'cloud-access': {
+      // cloud_* fields describe cluster configuration only (see isAvailable
+      // in macros/prop.js), so other scopes have no Cloud access value.
+      if (entry.config_scope !== 'cluster') return missing()
+      if (entry.cloud_readonly === true) return plain(raw ? 'readonly' : 'read-only')
+      if (entry.cloud_editable === true) return plain('editable')
+      if (entry.cloud_supported === false) return plain(raw ? 'unsupported' : 'not available')
+      return missing()
+    }
+    default:
+      return { ok: false, reason: 'unsupported' }
+  }
+}
+
+module.exports = {
+  FIELDS,
+  FIELD_ALIASES,
+  FORMAT_HUMAN,
+  FORMAT_RAW,
+  normalizeField,
+  fieldValue,
+  unitOf,
+  humanizeDuration,
+  humanizeBytes,
+  humanizeNumber,
+}

package/macros/PROPERTY_AND_ENTERPRISE_REFERENCES.adoc

@@ -35,6 +35,29 @@ Every release series has its own copy of that data, and the build picks the copy
 
 *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.
 
+=== Property values: the propval macro
+
+`prop:` marks a property's *name*. Prose often states its *value* too: "defaults to 128 MiB", "the minimum is one minute". Typed by hand, those drift when a release changes a default, and nothing notices. A real example: the disk space page said `log_segment_size` defaults to 1 GiB long after the default became 128 MiB.
+
+`propval:` renders the value from the same property data instead:
+
+[,asciidoc]
+----
+Set prop:log_segment_ms[], which defaults to propval:log_segment_ms[default].
+----
+
+That renders "defaults to 2 weeks". Other fields are `type`, `unit`, `min`, `max`, `restart`, `nullable`, `values`, `scope`, `introduced`, `visibility`, `restored`, `aliases`, and `cloud-access`, and `format=raw` gives the exact value (`1209600000`). The full list is in link:REFERENCE.adoc#propval[the macros reference].
+
+*It reads the same data as prop:, chosen the same way.* A 25.3 page gets 25.3's value, a beta page gets the newest release candidate's, and a Cloud page gets the newest GA value. The code is shared, not copied, so the two macros can't drift apart.
+
+*It agrees with the reference tables.* Values are formatted by the same helpers that render the property reference pages, so "2 weeks" in prose and "2 weeks" in the Default cell come from one place. Byte counts read as `128 MiB` only where the reference says the unit is bytes; where the data gives no unit, the exact number renders rather than a guessed unit.
+
+*It never guesses.* When the build can't verify a value (no data for the page's version, an unknown property, a field the property doesn't have, a property Cloud readers can't set), the page shows a visible `<unknown default>` and the build log says why. A wrong number is worse than an obvious gap.
+
+*Cloud pages state fewer values.* The Cloud property reference shows no defaults, because Cloud configures them, so `propval:x[default]` on a Cloud page renders the placeholder with a warning. Keep default values in `ifndef::env-cloud[]` content, or use `cloud-access` to say whether a Cloud user can change the property.
+
+To find the hand-written values already in a repo, run `doc-tools generate migrate-property-values`. It reports every value stated next to a property mention, compares it with the data for that repo's version, and flags mismatches, which are usually real doc errors. It also reports stale example output, such as an `rpk topic describe` row with source `DEFAULT_CONFIG` that shows an old default. `--write` replaces only exact matches, never a mismatch or example output.
+
 === 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.
@@ -106,7 +129,8 @@ Cloud is different from Kubernetes here, not just another context to adapt to. R
 
 * 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 extensions preview site's `property-values-test` page shows every `propval:` field, both formats, and each placeholder case.
 
 == 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.
+Nothing in the docs claims a name is a property, states a property's value, or marks a feature enterprise unless a writer said so explicitly *and* the build verified it against the source of truth.

package/macros/README.adoc

@@ -58,7 +58,9 @@ IMPORTANT: Macros must be registered under the `asciidoc.extensions` key in your
 === Inline macros
 
 * **glossterm** - Reference glossary terms with tooltips
-* **config_ref** - Link to configuration properties
+* **prop** - Reference a configuration property, with a validated tooltip and optional link
+* **propval** - Render a property's default, minimum, unit, or other value from the property data
+* **config_ref** - Link to configuration properties (deprecated; use prop)
 * **helm_ref** - Link to Helm chart values
 * **badge** - Display status badges
 

package/macros/REFERENCE.adoc

@@ -223,7 +223,7 @@ Registered together with the `enterprise` inline macro.
 
 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 checks that a property is actually available to the audience reading the page, and links it only where a page documents it. It validates against the published property data: a `redpanda-properties-<tag>.json` attachment in the `reference` module, the same data the tooltips fetch at runtime. See <<prop-availability>> for which properties each doc set may reference and <<prop-version-selection>> for which file a given page uses. To migrate existing plain-backtick property mentions, use `doc-tools generate migrate-property-refs`.
+The macro checks that a property is actually available to the audience reading the page, and links it only where a page documents it. It validates against the published property data: a `redpanda-properties-<tag>.json` attachment in the `reference` module, the same data the tooltips fetch at runtime. See <<prop-availability>> for which properties each doc set may reference and <<prop-version-selection>> for which file a given page uses. To migrate existing plain-backtick property mentions, use `doc-tools generate migrate-property-refs`. To render a property's value (its default, minimum, unit, and so on) rather than its name, use <<propval>>.
 
 === Usage
 
@@ -331,6 +331,163 @@ asciidoc:
     - '@redpanda-data/docs-extensions-and-macros/macros/prop'
 ----
 
+== propval
+
+This inline macro renders one value from the property data as plain text, so a sentence such as "defaults to 2 weeks" is generated from the same data as the property reference instead of typed by hand. Hand-typed values drift when a release changes a default, and nothing catches it.
+
+[,asciidoc]
+----
+Set prop:log_segment_ms[], which defaults to propval:log_segment_ms[default].
+The minimum is propval:log_segment_ms[min].
+Changing prop:cloud_storage_enabled[] requires a restart: propval:cloud_storage_enabled[restart].
+The exact default is `propval:log_segment_ms[default,format=raw]`.
+----
+
+Rendered against `redpanda-properties-v26.2.4.json`, those lines read: "defaults to 2 weeks", "The minimum is 1 minute", "requires a restart: yes", and "The exact default is `1209600000`".
+
+`propval:` is registered by the `prop` macro's extension, so a playbook that registers `macros/prop` has both. It shares every data decision with `prop:` rather than copying them: the same dataset for the page's version (<<prop-version-selection>>), the same `property-validate` modes, the same Cloud availability gate (<<prop-availability>>), and the same refusal to use a neighbouring release's data when a version has none.
+
+=== Usage
+
+The target is the property name. The first positional attribute (or `field=`) names the field, and defaults to `default`.
+
+[cols="1,2,2"]
+|===
+| Field | Source in the property JSON | Example (v26.2.4)
+
+| `default`
+| `default`, formatted as the reference table formats it. The human-readable form is the table's parenthetical (`default_human_readable`) when the data has one.
+| `log_segment_ms`: `2 weeks`; `fetch_max_bytes`: `55 MiB`; `cloud_storage_enabled`: `false`; `node_id`: `null`
+
+| `type`
+| `type`
+| `integer`
+
+| `unit`
+| `units`, else the unit the table derives from the name suffix (`_ms`, `_bytes`, and so on)
+| `milliseconds`
+
+| `min`, `max`
+| `minimum`, `maximum`, humanized with the unit
+| `log_segment_ms` min: `1 minute`
+
+| `restart`
+| `needs_restart`
+| `yes` or `no`
+
+| `nullable`
+| `nullable`
+| `yes` or `no`
+
+| `values`
+| `enum` (or `items.enum` for arrays), each value as inline code, because some values contain commas
+| `none`, `delete`, `compact`, `compact,delete`
+
+| `scope`
+| `config_scope`
+| `cluster`, `broker`, or `topic`
+
+| `introduced`
+| `version`
+| `v26.1.1`
+
+| `visibility`
+| `visibility`
+| `user`, `tunable`
+
+| `restored`
+| `gets_restored` (restored on Whole Cluster Restore)
+| `yes` or `no`
+
+| `aliases`
+| `aliases`
+| comma-separated names
+
+| `cloud-access`
+| `cloud_editable` and `cloud_readonly`, for cluster properties only
+| `editable`, `read-only`, or `not available`
+|===
+
+The JSON key names and table labels also work as field names: `minimum`, `maximum`, `needs_restart`, `units`, `enum`, `config_scope`, `version`, `gets_restored`.
+
+format::
+`human` (default) or `raw`. `raw` gives the exact value: the code value in the reference table for `default`, the plain number for `min` and `max`, `true` or `false` for the yes-or-no fields, and a JSON array for `values` and `aliases`.
+
+The output is a `<span>` with the stable class `property-value` and `data-property` and `data-field` attributes. It is plain text with no tooltip; mark the name with `prop:` for that. The macro works inside backticks, so `` `propval:x[default,format=raw]` `` renders as inline code. Don't put `values` inside backticks: it already renders each value as inline code, and backticks would nest one code element inside another.
+
+=== Formatting
+
+Values come from the reference generator's own helpers, so prose and the reference tables cannot disagree:
+
+* `default` uses `formatPropertyValue`, the helper that renders the table's Default cell. In the human form, a duration uses the table's parenthetical when the data has one.
+* A duration with no parenthetical in the data is humanized by a port of the extractor's `format_time_human_readable`, the function that produced the parenthetical: the largest unit that divides the value evenly, else the value in its own unit (`1500 milliseconds`).
+* A byte count renders in IEC units (`128 MiB`) only when the table's Unit row says bytes and the value is an exact multiple. Otherwise the exact number renders. `log_segment_size` and `segment.bytes` have no unit in the data or the table, so they render `134217728`. Adding `units` for them belongs in the property extractor, not in prose.
+* Negative numbers are sentinels (`-1` for unlimited) and render as written.
+* `null`, an empty string, and booleans render as the table renders them: `null`, `null`, `true`, `false`.
+* A topic property that the data leaves unset, such as `retention.bytes`, renders `null` for `default`, as the table does. The topic inherits its cluster property (`corresponding_cluster_property` in the data), so in prose, point to that property with `prop:`, such as "inherits prop:retention_bytes[]", rather than saying the default is `null`.
+
+=== Failures
+
+A value has no safe fallback, so whenever the build cannot verify one, `propval:` renders a visible placeholder such as `<unknown default>` (class `property-value property-value-unknown`) and logs why, naming the property, the field, and the dataset. It never renders a guessed value. The cases:
+
+* The page's version has no property data, or the component has none (the same diagnostic `prop:` logs, plus one for the `propval:` call).
+* The property is not in the page's dataset.
+* The property is not available on a Cloud page (`cloud_supported: false` on a cluster property).
+* The field is not one `propval:` supports.
+* The property has no such field in the data, for example `max` on a property with no maximum, or `default` on a deprecated property the data gives no default.
+* The value is an integer beyond JavaScript's exact range (the 2^64^-1 sentinel of `virtual_cluster_min_producer_ids`), which `JSON.parse` has already rounded.
+* On a Cloud page, the field is one the Cloud property reference does not show: `default`, `introduced`, `visibility`, `restored`, and `aliases`. The reference renders those only outside `env-cloud` (Cloud shows "Available in the Redpanda Cloud Console" in the Default row), so a Cloud page cannot state them either. Put the sentence in an `ifndef::env-cloud[]` block, or use a field the Cloud reference shows, such as `cloud-access`.
+
+With `property-validate` set to `error`, an unknown property, an unsupported field, a field the property does not have, a property not available on Cloud, or a field the Cloud reference does not show fails the build. The last two appear only in the Cloud build, so cloud-docs needs `property-validate: error` to catch single-sourced prose that would render a placeholder. With `off`, the placeholder is still rendered and still reported, because `off` means "do not check names", and a silent `<unknown default>` would reach readers unnoticed.
+
+=== Migrating hand-written values
+
+`doc-tools generate migrate-property-values` finds hand-written values next to a property mention ("defaults to X", "the default is X", "default: X", "minimum X", "is X by default") and checks each against the data for the repo's own version, selected exactly as `prop:` selects it. It writes a JSON and a Markdown report. Each finding is one of:
+
+exact:: The written text is what `propval:` renders. Auto-safe when the statement is in the same sentence as its property, no other property is named in that paragraph line or its list entry, the data value is not null, and the file is not release or upgrade notes. On a self-managed page, a `default` (or another field the Cloud reference hides), or any field of a property Cloud does not support, is auto-safe only inside `ifndef::env-cloud[]` or in a page (not a partial) with no `tag::` regions. Otherwise the page may be single-sourced into cloud-docs, where `propval:` renders a placeholder, so the finding is proposed only: wrap the sentence in `ifndef::env-cloud[]` first.
+equivalent:: Same value, different wording (`7 days` and `1 week`). Proposed, never applied.
+mismatch:: The written value differs from the data. Likely a doc error. Never applied.
+unset:: The data default is null (not set), but the prose states a value. Redpanda often computes a fallback at runtime for an unset property, such as 10% of free disk for `compaction_ctrl_backlog_size`, so confirm the value in the source. Never applied.
+unverifiable:: Not comparable: unparseable, a field the property does not have, a sentence qualified to another audience or release ("In Redpanda Cloud", "in earlier versions", "If the default is"), content inside `ifdef::env-cloud[]` on a self-managed page, a Cloud default, or "no default" for a topic property, which inherits its cluster property.
+example-output:: A value shown in command output inside a listing, literal, or fenced block. These findings are counted and listed apart from prose findings, and never applied. Each has a verdict: `stale`, `matches`, or `unverifiable` with a reason.
+
+Tables are scanned too. A statement in a cell belongs to the property that opens the row or cell, and a `Default` column states the default of the row's property. Table findings are reported but never applied.
+
+`--write` applies only auto-safe exact matches. The tool skips prose inside code blocks, headings, attribute entries, comment lines, `ifndef::env-cloud[]` content on a Cloud page, and generated content. For cloud-docs, pass the docs checkout with `--lender` so Cloud can borrow its GA data.
+
+[,bash]
+----
+npx doc-tools generate migrate-property-values --docs-dir . --report-dir ./propval-report
+npx doc-tools generate migrate-property-values --docs-dir ../cloud-docs --lender . --report-dir ./propval-report-cloud
+----
+
+==== Example output
+
+The tool reads these output shapes: `rpk topic describe` config tables (`KEY VALUE SOURCE`), `name=value (SOURCE)` lines, `kafka-configs --describe` lines (the first synonym's source), Key/Value/Source records in JSON or YAML (debug bundles, Topic resource status), `rpk cluster config get` output in the same block or an Input/Output pair, `rpk cluster config export` YAML, and Admin API `/v1/cluster_config` JSON. `rpk cluster config status` output states no values. A topic property is compared with the cluster property it inherits, taken from the data's `corresponding_cluster_property`, or `alternate_cluster_property` when the same output shows `cleanup.policy` set to compact. A Kafka broker alias such as `log.segment.bytes` is not in the data, so the Redpanda-named synonym row is compared. Values are compared exactly as raw bytes, milliseconds, booleans, or enum text. `-1` matches a limit that the data leaves unset.
+
+A row is compared only when it asserts the default. A row with source `DEFAULT_CONFIG` or `DEFAULT` asserts it. Output with no source column (`config get`, `export`, Admin API) asserts it only when the text just before the block mentions the default. The following are `unverifiable`, with the first matching reason:
+
+* `not-default-source`: Another source, such as `DYNAMIC_TOPIC_CONFIG` or `STATIC_BROKER_CONFIG`.
+* `ifdef::env-cloud` on a self-managed page, or `cloud-default` on a Cloud page.
+* `set-earlier-on-page`: The page sets the cluster property before the block, as `name=value`, `name: value` (including Helm `config.cluster.name`), or `rpk cluster config set name value`. A topic-level override doesn't count, because it would change the row's source.
+* `helm-operator-context`: A Kubernetes page (`kubernetes/` path or `k-` file name), or a command run through `kubectl` or `helm`. The chart or operator may set the value.
+* `dev-or-bootstrap-config`: The page starts Redpanda in `dev-container` mode, with `rpk container start`, or from a bootstrap file.
+* `current-value`: Output with no source column, and no mention of the default before it.
+* `unset-in-data` or `not-comparable`.
+
+The report lists stale examples in their own table. It lists unverifiable rows whose value differs from the default in a context that may set them (other than `not-default-source`) for a human to check.
+
+=== Registration
+
+Registered by the `prop` macro's extension:
+
+[,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/USER_GUIDE.adoc

@@ -25,6 +25,7 @@ asciidoc:
   extensions:
     - '@redpanda-data/docs-extensions-and-macros/macros/glossary'
     - '@redpanda-data/docs-extensions-and-macros/macros/config-ref'
+    - '@redpanda-data/docs-extensions-and-macros/macros/prop'
     - '@redpanda-data/docs-extensions-and-macros/macros/helm-ref'
 ----
 
@@ -63,6 +64,33 @@ config_ref:cleanup.policy,false[]
 * `isLink` - Whether to create a link (true/false, required)
 * `path` - Document path for link (required if isLink is true)
 
+=== prop and propval - Property names and values
+
+Mark a configuration property's name, and render its values from the property data:
+
+[,asciidoc]
+----
+Set prop:log_segment_ms[], which defaults to propval:log_segment_ms[default].
+The minimum is propval:log_segment_ms[min].
+----
+
+With Redpanda 26.2 data, that renders "defaults to 2 weeks" and "The minimum is 1 minute".
+
+*Syntax:* `prop:name[]` and `propval:name[field,format=raw]`
+
+* `name` - Property name (required)
+* `field` - `default` (when omitted), `type`, `unit`, `min`, `max`, `restart`, `nullable`, `values`, `scope`, `introduced`, `visibility`, `restored`, `aliases`, or `cloud-access`
+* `format=raw` - The exact value (`1209600000`) instead of the human-readable one (`2 weeks`)
+
+Register `@redpanda-data/docs-extensions-and-macros/macros/prop`, which provides both macros. If a value can't be verified for the page's version, the page shows `<unknown default>` and the build log says why. See link:REFERENCE.adoc#propval[the macros reference] for every field and failure case.
+
+To find hand-written values in a repo and check them against the data:
+
+[,bash]
+----
+npx doc-tools generate migrate-property-values --docs-dir . --report-dir ./propval-report
+----
+
 === helm_ref - Helm value references
 
 Link to Helm chart values: