[docs-infra] Do not escape pipes (|) inside code blocks (#47139)

Author: ZeeshanTamboli

docs/translations/api-docs/button/button.json

@@ -25,7 +25,7 @@
       "description": "The URL to link to when the button is clicked. If defined, an <code>a</code> element will be used as the root node."
     },
     "loading": {
-      "description": "If <code>true</code>, the loading indicator is visible and the button is disabled. If <code>true \\| false</code>, the loading wrapper is always rendered before the children to prevent <a href=\"https://github.com/mui/material-ui/issues/27853\">Google Translation Crash</a>."
+      "description": "If <code>true</code>, the loading indicator is visible and the button is disabled. If <code>true | false</code>, the loading wrapper is always rendered before the children to prevent <a href=\"https://github.com/mui/material-ui/issues/27853\">Google Translation Crash</a>."
     },
     "loadingIndicator": {
       "description": "Element placed before the children if the button is in loading state. The node should contain an element with <code>role=&quot;progressbar&quot;</code> with an accessible name. By default, it renders a <code>CircularProgress</code> that is labeled by the button itself."

docs/translations/api-docs/icon-button/icon-button.json

@@ -17,7 +17,7 @@
       "description": "If given, uses a negative margin to counteract the padding on one side (this is often helpful for aligning the left or right side of the icon with content above or below, without ruining the border size and shape)."
     },
     "loading": {
-      "description": "If <code>true</code>, the loading indicator is visible and the button is disabled. If <code>true \\| false</code>, the loading wrapper is always rendered before the children to prevent <a href=\"https://github.com/mui/material-ui/issues/27853\">Google Translation Crash</a>."
+      "description": "If <code>true</code>, the loading indicator is visible and the button is disabled. If <code>true | false</code>, the loading wrapper is always rendered before the children to prevent <a href=\"https://github.com/mui/material-ui/issues/27853\">Google Translation Crash</a>."
     },
     "loadingIndicator": {
       "description": "Element placed before the children if the button is in loading state. The node should contain an element with <code>role=&quot;progressbar&quot;</code> with an accessible name. By default, it renders a <code>CircularProgress</code> that is labeled by the button itself."

packages/api-docs-builder/utils/escapeCell.test.ts

@@ -0,0 +1,52 @@
+import { expect } from 'chai';
+import escapeCell from './escapeCell';
+
+describe('escapeCell', () => {
+  it('escapes pipes outside backticks', () => {
+    const input = 'true | false';
+    const result = escapeCell(input);
+    expect(result).to.equal('true \\| false');
+  });
+
+  it('does not escape pipes inside single backticks', () => {
+    const input = '`true | false`';
+    const result = escapeCell(input);
+    expect(result).to.equal('`true | false`');
+  });
+
+  it('does not escape pipes inside multiple inline code spans', () => {
+    const input = 'Use `a | b` and `x | y` here';
+    const result = escapeCell(input);
+    expect(result).to.equal('Use `a | b` and `x | y` here');
+  });
+
+  it('escapes pipes in normal text but not inside backticks', () => {
+    const input = '`a | b` or c | d';
+    const result = escapeCell(input);
+    expect(result).to.equal('`a | b` or c \\| d');
+  });
+
+  it('handles strings without any pipes', () => {
+    const input = 'no pipes here';
+    const result = escapeCell(input);
+    expect(result).to.equal('no pipes here');
+  });
+
+  it('keeps < inside code spans but escapes outside', () => {
+    const input = 'Use <b>bold</b> and `<div>` tags';
+    const result = escapeCell(input);
+    expect(result).to.equal('Use &lt;b>bold&lt;/b> and `<div>` tags');
+  });
+
+  it('does not escape pipe at string start or end inside backticks', () => {
+    const input = '`| start and end |`';
+    const result = escapeCell(input);
+    expect(result).to.equal('`| start and end |`');
+  });
+
+  it('escapes pipe at string start or end outside backticks', () => {
+    const input = '| start | and end |';
+    const result = escapeCell(input);
+    expect(result).to.equal('\\| start \\| and end \\|');
+  });
+});

packages/api-docs-builder/utils/escapeCell.ts

@@ -1,4 +1,15 @@
+function escapePipesOutsideBackticks(value: string): string {
+  // Split into chunks that are either code spans or normal text.
+  // Capturing group keeps the code chunks in the array.
+  return value
+    .split(/(`[^`]*`)/g)
+    .map((chunk) => (chunk.startsWith('`') ? chunk : chunk.replace(/\|/g, '\\|')))
+    .join('');
+}
+
 export default function escapeCell(value: string): string {
   // As the pipe is use for the table structure
-  return value.replace(/</g, '&lt;').replace(/`&lt;/g, '`<').replace(/\|/g, '\\|');
+  const newValue = escapePipesOutsideBackticks(value);
+
+  return newValue.replace(/</g, '&lt;').replace(/`&lt;/g, '`<');
 }