fix(rpcn-docs): render code spans and metadata lists literally

__tests__/tools/description-partials.test.js

@@ -1461,3 +1461,31 @@ describe('intro.hbs shares the renderer with the description partial', () => {
     expect(out).toContain('Paragraph.\n\n== Operators');
   });
 });
+
+describe('protectCodeSpans', () => {
+  const { protectCodeSpans, escapePlaceholderBraces } = require('../../tools/redpanda-connect/helpers/renderConnectDescription.js');
+  const escape = (text) => protectCodeSpans(escapePlaceholderBraces(text));
+
+  test('wraps code spans holding unconstrained markers in a passthrough', () => {
+    expect(escape('custom objects end with `__c`; Big Objects end with `__b`'))
+      .toBe('custom objects end with `+__c+`; Big Objects end with `+__b+`');
+    expect(escape("exclude `'.git/**', '**/*.png'`")).toBe("exclude `+'.git/**', '**/*.png'+`");
+  });
+
+  test('leaves ordinary spans, existing passthroughs, and verbatim blocks alone', () => {
+    const text = 'plain `snake_case` and `+__c+`\n\n----\nkey: `__c`\n----';
+    expect(escape(text)).toBe(text);
+  });
+
+  test('removes the brace escape inside a wrapped span, where it would render literally', () => {
+    expect(escape('a `__$x {name}` span')).toBe('a `+__$x {name}+` span');
+  });
+
+  renderTest('renders the markers literally instead of as emphasis', () => {
+    const html = asciidoctor.convert(escape('ends with `__c`; Big Objects end with `__b`; match `**/*.md`'));
+    expect(html).toContain('<code>__c</code>');
+    expect(html).toContain('<code>__b</code>');
+    expect(html).toContain('<code>**/*.md</code>');
+    expect(html).not.toMatch(/<(em|strong)>/);
+  });
+});

__tests__/tools/metadata-partials.test.js

@@ -688,3 +688,20 @@ describe('resolvePageTypeDir', () => {
     expect(resolvePageTypeDir(root, '')).toBe('');
   });
 });
+
+describe('normalize-metadata: lists and nested parentheses', () => {
+  test('inline-codes a field name whose description nests parentheses', () => {
+    const out = normalizeMetadataBlock('== Metadata\n\n- lsn (The commit LSN. Not present on snapshot (`read`) messages.)');
+    expect(out).toContain('- `lsn` (The commit LSN. Not present on snapshot (`read`) messages.)');
+  });
+
+  test('separates a list from the paragraph directly above it', () => {
+    const out = normalizeMetadataBlock('== Metadata\n\nIf HTTPS is enabled, the following fields are added as well:\n- `tls_version`\n- `tls_subject`');
+    expect(out).toBe('== Metadata\n\nIf HTTPS is enabled, the following fields are added as well:\n\n- `tls_version`\n- `tls_subject`');
+  });
+
+  test('does not split a list at a wrapped bullet line', () => {
+    const block = '== Metadata\n\n- `a` (first line\n  continues)\n- `b`';
+    expect(normalizeMetadataBlock(block)).toBe(block);
+  });
+});

tools/redpanda-connect/helpers/renderConnectDescription.js

@@ -58,7 +58,7 @@ function hasMarkdownHeadings (body) {
 module.exports = function renderConnectDescription (item) {
   const body = descriptionWithMetadataInclude(item);
   if (!body || !body.trim()) return '';
-  return escapePlaceholderBraces(ensureHeadingSeparation(body.trim()));
+  return protectCodeSpans(escapePlaceholderBraces(ensureHeadingSeparation(body.trim())));
 };
 
 /**
@@ -106,6 +106,34 @@ function escapePlaceholderBraces (body) {
   )).join('\n');
 }
 
+// Doubled characters that Asciidoctor treats as unconstrained emphasis, bold
+// and highlight markers. They apply inside a backtick code span and pair up
+// across spans, so `__c` and `__b` on one line render as <em> between them,
+// and a glob like `'**/*.md'` renders as <strong> (live on the salesforce and
+// git inputs).
+const UNCONSTRAINED_MARKERS = /__|\*\*|##/;
+
+/**
+ * Wrap inline code spans that contain unconstrained formatting markers in a
+ * `+...+` passthrough, so the span renders literally. Spans are left alone
+ * when they are already passthroughs or start or end with whitespace (which
+ * only happens when backticks on a line don't pair up as code spans).
+ *
+ * Runs after escapePlaceholderBraces: a passthrough applies no attribute
+ * substitution, so the `\{` escape it added inside the span would render as a
+ * literal backslash and is removed again. Listing blocks and fences are
+ * verbatim and stay untouched.
+ */
+function protectCodeSpans (body) {
+  return annotateVerbatimLines(body).map(({ line, verbatim }) => (
+    verbatim ? line : line.replace(/`([^`\n]+)`/g, (span, content) => {
+      if (!UNCONSTRAINED_MARKERS.test(content)) return span;
+      if (/^\+|\+$/.test(content) || /^\s|\s$/.test(content)) return span;
+      return `\`+${content.replace(/\\\{/g, '{')}+\``;
+    })
+  )).join('\n');
+}
+
 /**
  * Depth of the first structural heading (AsciiDoc `=` or markdown-compat
  * `#`) outside listing blocks and fences, or null when the body has none.
@@ -126,6 +154,7 @@ function firstHeadingDepth (body) {
 module.exports.hasStructuralHeadings = hasStructuralHeadings;
 module.exports.hasMarkdownHeadings = hasMarkdownHeadings;
 module.exports.escapePlaceholderBraces = escapePlaceholderBraces;
+module.exports.protectCodeSpans = protectCodeSpans;
 module.exports.ensureHeadingSeparation = ensureHeadingSeparation;
 module.exports.firstHeadingDepth = firstHeadingDepth;
 module.exports.LONG_HEADINGLESS_THRESHOLD = LONG_HEADINGLESS_THRESHOLD;

tools/redpanda-connect/helpers/renderConnectFields.js

@@ -2,7 +2,7 @@ const yaml = require('yaml');
 const renderYamlList = require('./renderYamlList');
 const handlebars = require('handlebars');
 const { connectFieldName } = require('./flattenConnectFields');
-const { escapePlaceholderBraces } = require('./renderConnectDescription');
+const { escapePlaceholderBraces, protectCodeSpans } = require('./renderConnectDescription');
 
 /**
  * Renders the children of a configuration object into AsciiDoc.
@@ -71,7 +71,7 @@ module.exports = function renderConnectFields(children, prefix = '') {
     // --- Beta badge logic (now uses is_beta) ---
     // Escaped before the badge is prepended, not after: the badge's own
     // tooltip={page-beta-text} is a real attribute reference and must survive.
-    let desc = escapePlaceholderBraces(child.description || '');
+    let desc = protectCodeSpans(escapePlaceholderBraces(child.description || ''));
     if (child.is_beta) {
       // Remove any leading "BETA:" label (case-insensitive, trims leading whitespace)
       desc = 'badge::[label=Beta, size=large, tooltip={page-beta-text}]\n\n' + desc.replace(/^\s*BETA:\s*/i, '');

tools/redpanda-connect/helpers/renderConnectMetadata.js

@@ -2,6 +2,7 @@
 
 const { extractMetadata } = require('../metadata-utils.js');
 const { normalizeMetadataBlock } = require('../normalize-metadata.js');
+const { protectCodeSpans } = require('./renderConnectDescription.js');
 
 /**
  * Handlebars helper: return the `== Metadata` block extracted from a connector
@@ -11,5 +12,5 @@ const { normalizeMetadataBlock } = require('../normalize-metadata.js');
  * @returns {string}
  */
 module.exports = function renderConnectMetadata (description) {
-  return normalizeMetadataBlock(extractMetadata(description));
+  return protectCodeSpans(normalizeMetadataBlock(extractMetadata(description)));
 };

tools/redpanda-connect/normalize-metadata.js

@@ -5,7 +5,7 @@
  * metadata partials are consistent regardless of how each connector authored
  * its metadata section upstream.
  *
- * Two inconsistencies are normalized:
+ * Three inconsistencies are normalized:
  *   1. Some connectors wrap their field list in a fenced code block
  *      (```text ... ``` or ``` ... ```) of bare names; others use an AsciiDoc
  *      bullet list with the field name in inline code. We strip the fences
@@ -14,6 +14,9 @@
  *      identifier) is wrapped in inline code. Descriptive bullets such as
  *      "All headers (only first values are taken)" are left as prose, and
  *      bullets that already contain inline code are left untouched.
+ * *   3. A list glued to the paragraph above it ("…added as well:" directly
+ *      followed by "- field") renders as one paragraph with literal dashes,
+ *      so a blank line is inserted before it.
  *
  * Everything else (intro sentences, notes, `===` subheadings that legitimately
  * group metadata by operation, non-field-list fenced blocks, and AsciiDoc
@@ -34,7 +37,9 @@ const { BLOCK_DELIMITER } = require('./metadata-utils.js');
 // description separated by ":" or " - ". This distinguishes real field bullets
 // from descriptive ones like "All headers ..." (which start with a capital).
 // The description may itself contain inline code, so it is matched loosely.
-const FIELD_BULLET = /^([a-z][a-z0-9_]*)((?:\s*\([^)]*\))?(?:\s*(?::|-)\s.*)?)$/s;
+// A parenthetical description may nest its own parentheses, for example
+// "lsn (... Not present on snapshot (`read`) messages.)".
+const FIELD_BULLET = /^([a-z][a-z0-9_]*)((?:\s*\(.*\))?(?:\s*(?::|-)\s.*)?)$/s;
 
 function normalizeBullet (prefix, content) {
   // Skip only when the field name itself is already inline-coded; a backtick
@@ -68,6 +73,20 @@ function normalizeMetadataBlock (block) {
   if (!block || typeof block !== 'string') return block;
   const lines = block.split('\n');
   const out = [];
+  // True while the lines since the last blank line belong to a list, so a
+  // bullet after a wrapped bullet line continues the list instead of starting
+  // a new one.
+  let inList = false;
+  const pushBullet = (text) => {
+    const prev = out.length ? out[out.length - 1] : '';
+    if (!inList && prev.trim() !== '' && !/^[=/+]/.test(prev)) out.push('');
+    inList = true;
+    out.push(text);
+  };
+  const pushLine = (text) => {
+    if (text.trim() === '') inList = false;
+    out.push(text);
+  };
 
   for (let i = 0; i < lines.length; i++) {
     // AsciiDoc literal/listing block: pass the whole `----` … `----` region
@@ -100,7 +119,8 @@ function normalizeMetadataBlock (block) {
         // Drop the fences and render the fields as a normal bullet list.
         for (const c of content) {
           const b = c.match(BULLET);
-          out.push(b ? normalizeBullet(b[1], b[2]) : c);
+          if (b) pushBullet(normalizeBullet(b[1], b[2]));
+          else pushLine(c);
         }
       } else {
         // Not a field list (e.g. a YAML example) — keep verbatim.
@@ -112,7 +132,8 @@ function normalizeMetadataBlock (block) {
     } else {
       // Bare bullet outside a fence: normalize the field name too.
       const b = lines[i].match(BULLET);
-      out.push(b ? normalizeBullet(b[1], b[2]) : lines[i]);
+      if (b) pushBullet(normalizeBullet(b[1], b[2]));
+      else pushLine(lines[i]);
     }
   }