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

package/bin/doc-tools.js

@@ -2132,6 +2132,11 @@ automation
  * bullets — it is a CANDIDATE for the curation step that rewrites voice, adds
  * `Area::` labels, normalizes units, and phrases CVEs.
  *
+ * In phase 1, a backticked name that matches a property in the release
+ * series' redpanda-properties-<tag>.json becomes a `prop:<name>[link=true]` link. The
+ * file is found in modules/reference/attachments/ unless --properties-file
+ * names one. With no file, names stay monospace and a warning is logged.
+ *
  * @why
  * Release notes are the one reference surface whose source of truth is
  * engineer-authored prose rather than code, so the deterministic part
@@ -2164,6 +2169,7 @@ automation
   .option('--section-file <file>', 'Phase 2: a curated section (from the sm-release-notes skill) to insert (relative to repo root, must stay inside the repository)')
   .option('--date <date>', 'Authored release date as YYYY-MM-DD (required with --body; confirmed on the PR)')
   .option('--page <file>', 'Target release-notes page (relative to repo root, must stay inside the repository)', 'modules/reference/pages/releases/redpanda.adoc')
+  .option('--properties-file <file>', 'Phase 1: property JSON whose names become prop: links (relative to repo root, must stay inside the repository). Default: the newest redpanda-properties-<tag>.json in modules/reference/attachments/ for the tag\'s release series')
   .option('--section-only', 'Phase 1 only: print the candidate section and do not read or modify the page')
   .option('--dry-run', 'Print output to stdout instead of writing the page')
   .action(async (options) => {
@@ -2172,6 +2178,11 @@ automation
       buildReleaseSection,
       isGaTag,
     } = require('../tools/redpanda-release-notes/generate-release-notes.js')
+    const {
+      ATTACHMENTS_DIR,
+      findPropertiesFile,
+      loadPropertyNames,
+    } = require('../tools/redpanda-release-notes/property-names.js')
     try {
       const repoRoot = findRepoRoot()
 
@@ -2192,6 +2203,19 @@ automation
         return abs
       }
 
+      // Phase 1 links known property names. An explicit --properties-file must
+      // exist; a missing default only means names stay monospace.
+      const readPropertyNames = () => {
+        const file = options.propertiesFile
+          ? readInside(options.propertiesFile, '--properties-file')
+          : findPropertiesFile(path.join(repoRoot, ATTACHMENTS_DIR), options.tag)
+        if (!file) {
+          console.warn(`[release-notes] WARN: no property file for ${options.tag} in ${ATTACHMENTS_DIR}; property names stay monospace.`)
+          return undefined
+        }
+        return loadPropertyNames(file)
+      }
+
       // Phase-1 candidate preview: emit the candidate for the curation step. No
       // page is read or written — this is the LLM step's input, nothing else.
       if (options.sectionOnly) {
@@ -2203,7 +2227,9 @@ automation
           return
         }
         const body = fs.readFileSync(readInside(options.body, '--body'), 'utf8')
-        const section = buildReleaseSection({ body, version: options.tag, date: options.date })
+        const section = buildReleaseSection({
+          body, version: options.tag, date: options.date, propertyNames: readPropertyNames(),
+        })
         process.stdout.write(section)
         return
       }
@@ -2213,6 +2239,7 @@ automation
       const genArgs = { tag: options.tag, date: options.date, pageContent }
       if (hasBody) {
         genArgs.body = fs.readFileSync(readInside(options.body, '--body'), 'utf8')
+        genArgs.propertyNames = readPropertyNames()
       } else {
         genArgs.section = fs.readFileSync(readInside(options.sectionFile, '--section-file'), 'utf8')
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@redpanda-data/docs-extensions-and-macros",
-  "version": "5.56.1",
+  "version": "5.57.0",
   "description": "Antora extensions and macros developed for Redpanda documentation.",
   "keywords": [
     "antora",

package/tools/redpanda-release-notes/generate-release-notes.js

@@ -132,48 +132,90 @@ function insertReleaseSection(pageContent, sectionText) {
 }
 
 /**
- * Reorders the entries within each `=== category` of a curated section so that
- * entries sharing an `Area::` label sit together. Areas are ordered
- * ALPHABETICALLY (case-insensitive), so a given area sits in the same place on
- * every release instead of moving with the source's merge order; entries keep
- * their source order within an area, so the sort is stable. The label is
- * repeated per entry (not merged into one heading), so the page format is
- * unchanged — only the order of entries within a category changes. Running it on
- * an already-clustered section is a no-op, so it is safe to apply on every
- * release and on a backfill.
+ * Groups the entries within each `=== category` of a curated section by their
+ * `Area::` label. Areas are ordered ALPHABETICALLY (case-insensitive), so a given
+ * area sits in the same place on every release instead of moving with the
+ * source's merge order; entries keep their source order within an area, so the
+ * sort is stable. Each area is written ONCE per category, as the definition-list
+ * term, with its entries as a bulleted list under it:
  *
- * Only the clean single-line `Area:: description` definition-list form is
- * reordered. A category whose entries are not all of that form — a phase-1
- * candidate's plain `*` bullets, or a multi-line entry — is left in its original
- * order, so this is a safe no-op on anything it does not recognize. A curated
- * category (one with at least one `Area::` entry) that bails logs a warning, since
- * it then ships unclustered. Area keys are trimmed for grouping, so `Kafka API`
- * and `Kafka API ` are one area. Headings and any prose outside a category are
- * passed through untouched.
+ *   Cloud Topics::
+ *   * First entry.
+ *   * Second entry.
+ *
+ * An area with one entry still gets a one-item list. Input entries may be in
+ * either form: single-line `Area:: description` (what curation writes) or an
+ * already-grouped `Area::` paragraph with single-line `* ` items. A category can
+ * mix the two. Running it on its own output is a no-op, so it is safe to apply on
+ * every release, on a backfill, and on a section grouped by hand.
+ *
+ * A category with any other kind of entry (a phase-1 candidate's plain `*`
+ * bullets, or a multi-line entry) is not grouped, so this is a safe no-op on
+ * anything it does not recognize. Its entries keep their order and text. The
+ * one change is that single-line entries on adjacent lines come out with a
+ * blank line between them, which AsciiDoc renders the same way. Line endings
+ * in the output are LF. A curated category (one with at least
+ * one `Area::` entry) that is left as it is logs a warning, because it then
+ * ships ungrouped. Area keys are trimmed, so `Kafka API` and `Kafka API ` are one
+ * area, written as the trimmed label. Headings and any prose outside a category
+ * are passed through untouched.
  *
  * @param {string} sectionText - A rendered release section.
- * @return {string} The section with each category's entries clustered by area,
+ * @return {string} The section with each category's entries grouped by area,
  *   ending in a single newline.
  */
 function clusterSectionByArea(sectionText) {
-  // The area label is the text up to the first `:: ` (double-colon + space),
-  // which is the AsciiDoc definition-list term separator. A lazy match stops at
-  // that first separator, so a `::` later in the description is left alone. A
-  // leading list marker (`*`, `-`, `.`), at column zero or indented, is rejected
-  // so a plain bullet that happens to carry a `::` — a phase-1 candidate line —
-  // is not mistaken for an area entry; its category then bails and is left
-  // untouched.
-  const ENTRY_RE = /^(?!\s*[*.\-]+\s)(.+?)::\s/;
+  // A single-line entry: the area label is the text up to the first `:: `
+  // (double-colon + space), the AsciiDoc definition-list term separator. A lazy
+  // match stops at that first separator, so a `::` later in the description is
+  // left alone. A leading list marker (`*`, `-`, `.`), at column zero or
+  // indented, is rejected so a plain bullet that happens to carry a `::` (a
+  // phase-1 candidate line) is not mistaken for an area entry.
+  const ENTRY_RE = /^(?!\s*[*.\-]+\s)(.+?)::\s+(\S.*)$/;
+  // A grouped area: a term line with nothing after the `::`.
+  const TERM_RE = /^(?!\s*[*.\-]+\s)(.+?)::\s*$/;
+  // An item of a grouped area: one `* ` bullet on one line.
+  const ITEM_RE = /^\* (\S.*)$/;
+
+  // Parses one paragraph into [area, items], or null if it is not a recognized
+  // entry. A grouped paragraph must be a term line followed only by items.
+  const parseEntry = (para) => {
+    if (para.length === 1) {
+      const m = para[0].match(ENTRY_RE);
+      if (m) return [m[1].trim(), [m[2]]];
+    }
+    const t = para[0].match(TERM_RE);
+    if (t && para.length > 1) {
+      const items = [];
+      for (const line of para.slice(1)) {
+        const i = line.match(ITEM_RE);
+        if (!i) return null;
+        items.push(i[1]);
+      }
+      return [t[1].trim(), items];
+    }
+    return null;
+  };
+  const looksCurated = (para) => ENTRY_RE.test(para[0]) || TERM_RE.test(para[0]);
 
   // Tokenize into paragraphs: maximal runs of non-blank lines. In this format
-  // every heading and every entry is one such paragraph.
-  const lines = String(sectionText).replace(/\n+$/, '').split('\n');
+  // every heading, every single-line entry, and every grouped area is one such
+  // paragraph. Single-line entries on adjacent lines, with no blank line
+  // between them, are valid AsciiDoc too, so each one starts its own paragraph.
+  // A grouped area's term line does not match ENTRY_RE, so its bullets stay in
+  // one paragraph with it. CRLF and CR line endings become LF first: `.` in
+  // the patterns above does not match `\r`, so a CRLF line would match nothing.
+  const lines = String(sectionText).replace(/\r\n?/g, '\n').replace(/\n+$/, '').split('\n');
   const paragraphs = [];
   let current = [];
   for (const line of lines) {
     if (/^\s*$/.test(line)) {
       if (current.length) { paragraphs.push(current); current = []; }
     } else {
+      if (current.length === 1 && ENTRY_RE.test(current[0]) && ENTRY_RE.test(line)) {
+        paragraphs.push(current);
+        current = [];
+      }
       current.push(line);
     }
   }
@@ -181,38 +223,35 @@ function clusterSectionByArea(sectionText) {
 
   const out = [];
   let categoryEntries = null; // entry paragraphs of the open `=== category`
-  let categoryBail = false;   // the open category has an unrecognized entry
   let categoryTitle = '';     // the open category's heading text, for warnings
 
   const flushCategory = () => {
     if (!categoryEntries) return;
-    if (categoryBail) {
-      // A phase-1 bullet category is expected to bail. A curated one (it has at
-      // least one `Area::` entry) bailing means some entry spans several lines,
-      // so the whole category ships unclustered — say so rather than fail quietly.
-      if (categoryEntries.some((entry) => ENTRY_RE.test(entry[0]))) {
-        console.warn(`${LOG_TAG} WARN: "${categoryTitle}" not grouped by area: an entry is not a single-line \`Area:: description\` (for example a \`+\` continuation or a code block).`);
+    const parsed = categoryEntries.map(parseEntry);
+    if (parsed.some((e) => e === null)) {
+      // A phase-1 bullet category is expected to be left as it is. A curated one
+      // (it has at least one `Area::` entry) left as it is means some entry is
+      // neither form, so the whole category ships ungrouped. Say so rather than
+      // fail quietly.
+      if (categoryEntries.some(looksCurated)) {
+        console.warn(`${LOG_TAG} WARN: "${categoryTitle}" not grouped by area: an entry is neither a single-line \`Area:: description\` nor an \`Area::\` term with single-line \`* \` items (for example a \`+\` continuation or a code block).`);
       }
       for (const entry of categoryEntries) out.push(entry);
     } else {
       const order = [];
       const groups = new Map();
-      for (const entry of categoryEntries) {
-        // Trimmed, so a stray space before `::` does not split one area in two.
-        // Only the grouping key is trimmed; the entry text is emitted verbatim.
-        const key = entry[0].match(ENTRY_RE)[1].trim();
+      for (const [key, items] of parsed) {
         if (!groups.has(key)) { groups.set(key, []); order.push(key); }
-        groups.get(key).push(entry);
+        groups.get(key).push(...items);
       }
       // Areas alphabetical (case-insensitive), so an area lands in the same
       // place on every release; entries keep their source order within an area.
       order.sort((a, b) => a.localeCompare(b, 'en', { sensitivity: 'base' }));
       for (const key of order) {
-        for (const entry of groups.get(key)) out.push(entry);
+        out.push([`${key}::`, ...groups.get(key).map((item) => `* ${item}`)]);
       }
     }
     categoryEntries = null;
-    categoryBail = false;
   };
 
   for (const para of paragraphs) {
@@ -222,7 +261,6 @@ function clusterSectionByArea(sectionText) {
       flushCategory();
       out.push(para);
       categoryEntries = [];
-      categoryBail = false;
       categoryTitle = first.replace(/^===\s+/, '').trim();
     } else if (/^==\s/.test(first)) {
       // The release heading (or any other top-level heading) closes the open
@@ -232,7 +270,6 @@ function clusterSectionByArea(sectionText) {
       categoryEntries = null;
     } else if (categoryEntries) {
       categoryEntries.push(para);
-      if (para.length !== 1 || !ENTRY_RE.test(para[0])) categoryBail = true;
     } else {
       // Prose outside any category (for example an intro paragraph): untouched.
       out.push(para);
@@ -250,10 +287,11 @@ function clusterSectionByArea(sectionText) {
  * @param {string} options.body - The raw rpchangelog release body markdown.
  * @param {string} options.version - The release version (`v26.2.3` or `26.2.3`).
  * @param {string} options.date - The release date as `YYYY-MM-DD`.
+ * @param {Set<string>} [options.propertyNames] - Known property names to link as `prop:` macros.
  * @return {string} The rendered AsciiDoc section.
  */
-function buildReleaseSection({ body, version, date }) {
-  const { sections } = parseReleaseBody(body);
+function buildReleaseSection({ body, version, date, propertyNames }) {
+  const { sections } = parseReleaseBody(body, { propertyNames });
   return renderReleaseSection({ version, date, sections });
 }
 
@@ -306,9 +344,10 @@ function assertSectionMatchesTag(section, version) {
  * @param {string} options.tag - The release tag (`v26.2.3`).
  * @param {string} [options.date] - The authored release date as `YYYY-MM-DD` (phase 1 only).
  * @param {string} options.pageContent - The current target page content.
+ * @param {Set<string>} [options.propertyNames] - Known property names to link as `prop:` macros (phase 1 only).
  * @return {{status: 'ok'|'skipped', reason?: string, section?: string, content?: string}}
  */
-function generateReleaseNotes({ body, section, tag, date, pageContent }) {
+function generateReleaseNotes({ body, section, tag, date, pageContent, propertyNames }) {
   if (body == null && section == null) {
     throw new Error('Provide either body (phase 1) or section (phase 2).');
   }
@@ -337,7 +376,7 @@ function generateReleaseNotes({ body, section, tag, date, pageContent }) {
     // have to, and so a hand-written section is normalized the same way.
     finalSection = clusterSectionByArea(section);
   } else {
-    finalSection = buildReleaseSection({ body, version, date });
+    finalSection = buildReleaseSection({ body, version, date, propertyNames });
   }
   const content = insertReleaseSection(pageContent, finalSection);
   return { status: 'ok', section: finalSection, content };

package/tools/redpanda-release-notes/parse-release-body.js

@@ -8,7 +8,8 @@
 //
 // This module does ONLY the deterministic, no-judgment work: split into
 // sections, join wrapped bullet lines, strip source noise, unescape backticks,
-// de-duplicate backport repeats, and normalize category order/case. It does NOT
+// link known configuration properties, de-duplicate backport repeats, and
+// normalize category order/case. It does NOT
 // rewrite voice, add `Area::` labels, normalize units, phrase CVEs, or drop
 // bodyless entries — those need editorial judgment and belong to the curation
 // step that runs on the generated page.
@@ -88,18 +89,43 @@ function stripLeadingIssueRef(text) {
  * the editorial curation step.
  *
  * @param {string} raw - The joined raw bullet text.
+ * @param {Object} [options]
+ * @param {Set<string>} [options.propertyNames] - Known property names to link (see linkProperties).
  * @return {string} The cleaned entry text.
  */
-function cleanEntry(raw) {
+function cleanEntry(raw, { propertyNames } = {}) {
   let text = raw.replace(/\s+/g, ' ').trim();
   text = stripLeadingIssueRef(text);
   text = stripAttribution(text);
   text = text.replace(/\\`/g, '`');
+  text = linkProperties(text, propertyNames);
   text = normalizeUnits(text);
   text = escapeAsciiDocBraces(text);
   return text.trim();
 }
 
+/**
+ * Rewrites a backticked configuration property name as a `prop:` macro with
+ * `link=true`, so the page links it to the property reference. Without
+ * `link=true`, the macro shows only a hover tooltip. Engineers cannot write `prop:` in
+ * the source, because nothing resolves it outside the docs build, so this is
+ * where the link is added.
+ *
+ * Only an exact match for a known name is rewritten: `` `retention.ms` `` is,
+ * `` `retention.ms=1000` `` and `` `health_manager` `` are not. A name with no
+ * `_` or `.` (such as `admin` or `rack`) is never rewritten, because in prose
+ * those words usually mean something other than the property.
+ *
+ * @param {string} text - The entry text, with backticks already unescaped.
+ * @param {Set<string>} [propertyNames] - Known property names. Without it, the text is returned unchanged.
+ * @return {string} The text with known property names as `prop:<name>[link=true]`.
+ */
+function linkProperties(text, propertyNames) {
+  if (!propertyNames || propertyNames.size === 0) return text;
+  return text.replace(/`([\w.-]+)`/g, (match, name) =>
+    /[_.]/.test(name) && propertyNames.has(name) ? `prop:${name}[link=true]` : match);
+}
+
 /**
  * Rewrites the source's underscore data-size notation to the readable unit the
  * standard requires (`4_MiB` -> `4 MiB`). Only a digit followed by `_` and a
@@ -131,11 +157,13 @@ function escapeAsciiDocBraces(text) {
  * grouped by canonical category in page order.
  *
  * @param {string} body - The raw GitHub Release body markdown.
+ * @param {Object} [options]
+ * @param {Set<string>} [options.propertyNames] - Known property names to link as `prop:` macros.
  * @return {{sections: Array<{kind: string, title: string, entries: string[]}>}}
  *   Sections in page order (Features, Bug fixes, Improvements); a category with
  *   no entries is omitted.
  */
-function parseReleaseBody(body) {
+function parseReleaseBody(body, { propertyNames } = {}) {
   if (typeof body !== 'string' || body.trim() === '') {
     throw new Error('Release body is empty.');
   }
@@ -155,7 +183,7 @@ function parseReleaseBody(body) {
 
   const flush = () => {
     if (current !== null && currentKind && buckets[currentKind]) {
-      const entry = cleanEntry(current);
+      const entry = cleanEntry(current, { propertyNames });
       if (entry) buckets[currentKind].push(entry);
     }
     current = null;
@@ -231,6 +259,7 @@ module.exports = {
   stripAttribution,
   stripLeadingIssueRef,
   cleanEntry,
+  linkProperties,
   normalizeUnits,
   escapeAsciiDocBraces,
   PAGE_ORDER,

package/tools/redpanda-release-notes/property-names.js

@@ -0,0 +1,65 @@
+// Load the configuration property names that the release-notes generator links
+// as `prop:` macros. The names come from the same redpanda-properties-<tag>.json
+// attachment that the prop macro validates against, so a name linked here is a
+// name the docs build can resolve.
+
+const fs = require('fs');
+const path = require('path');
+
+// The attachment directory, relative to the docs repository root.
+const ATTACHMENTS_DIR = 'modules/reference/attachments';
+const PROPERTIES_JSON_RX = /^redpanda-properties-v(\d+)\.(\d+)\.(\d+)\.json$/;
+
+/**
+ * Returns the property names in a parsed property JSON file.
+ *
+ * @param {Object} json - Parsed redpanda-properties-<tag>.json content.
+ * @return {Set<string>} The property names.
+ * @throws {Error} If the file has no `properties` object.
+ */
+function propertyNamesFromJson(json) {
+  if (!json || typeof json.properties !== 'object' || json.properties === null) {
+    throw new Error('Property file has no "properties" object.');
+  }
+  return new Set(Object.keys(json.properties));
+}
+
+/**
+ * Finds the newest GA property file for a tag's release series. A 26.2 tag
+ * uses 26.2 data only, the same rule the prop macro applies to a page, so a
+ * property from another release series is never linked.
+ *
+ * @param {string} dir - The directory to search.
+ * @param {string} tag - The release tag (`v26.2.5` or `26.2.5`).
+ * @return {string|null} The path to the newest matching file, or null if there is none.
+ */
+function findPropertiesFile(dir, tag) {
+  const m = String(tag).match(/^v?(\d+)\.(\d+)\./);
+  if (!m || !fs.existsSync(dir)) return null;
+  const [, major, minor] = m;
+  let best = null;
+  for (const file of fs.readdirSync(dir)) {
+    const f = file.match(PROPERTIES_JSON_RX);
+    if (!f || f[1] !== major || f[2] !== minor) continue;
+    const patch = Number(f[3]);
+    if (!best || patch > best.patch) best = { patch, file };
+  }
+  return best ? path.join(dir, best.file) : null;
+}
+
+/**
+ * Reads the property names from a property JSON file.
+ *
+ * @param {string} file - Path to a redpanda-properties-<tag>.json file.
+ * @return {Set<string>} The property names.
+ */
+function loadPropertyNames(file) {
+  return propertyNamesFromJson(JSON.parse(fs.readFileSync(file, 'utf8')));
+}
+
+module.exports = {
+  ATTACHMENTS_DIR,
+  propertyNamesFromJson,
+  findPropertiesFile,
+  loadPropertyNames,
+};