Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
fix: escape angle brackets in generated SDK docs to prevent MDX parse errors
TypeScript generic types like <ArrayBufferLike> were being interpreted as JSX tags by the MDX parser, breaking both the link checker and Vercel deployment. Use <code> HTML tags with </> escaping for inline types in tables, and escape angle brackets in description text. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Sushmitha Mallesh committed
Mar 10, 2026 at 21:47 UTC
4cd9513905e1e2d1c74c9137766fbca078a28398
1 file changed
+37
-21
ts/packages/core/scripts/generate-docs.ts
+37
-21
@@ -16,10 +16,7 @@ import { fileURLToPath } from 'url';
16
const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
17
const PACKAGE_DIR = join(SCRIPT_DIR, '..');
18
const MODELS_DIR = join(PACKAGE_DIR, 'src/models');
19
-const OUTPUT_DIR = join(
20
- PACKAGE_DIR,
21
- '../../../docs/content/reference/sdk-reference/typescript'
22
-);
19
+const OUTPUT_DIR = join(PACKAGE_DIR, '../../../docs/content/reference/sdk-reference/typescript');
20
const TEMP_JSON = join(PACKAGE_DIR, '.typedoc-output.json');
21
22
// Internal classes that should NOT be documented (accessed via other APIs)
@@ -456,9 +453,9 @@ function generateMethodMdx(method: MethodDoc): string {
453
lines.push('|------|------|-------------|');
454
for (const param of sig.parameters) {
455
const opt = param.required ? '' : '?';
459
- const desc = escapeForMdx(param.description || '');
460
- const safeType = escapeForMdx(simplifyTypeForTable(param.type));
461
- lines.push(`| \`${param.name}${opt}\` | \`${safeType}\` | ${desc} |`);
456
+ const desc = escapeTextForMdx(param.description || '');
457
+ const typeCell = safeInlineType(simplifyTypeForTable(param.type));
458
+ lines.push(`| \`${param.name}${opt}\` | ${typeCell} | ${desc} |`);
459
}
460
} else {
461
// No descriptions - use simpler table
@@ -466,8 +463,8 @@ function generateMethodMdx(method: MethodDoc): string {
463
lines.push('|------|------|');
464
for (const param of sig.parameters) {
465
const opt = param.required ? '' : '?';
469
- const safeType = escapeForMdx(simplifyTypeForTable(param.type));
470
- lines.push(`| \`${param.name}${opt}\` | \`${safeType}\` |`);
466
+ const typeCell = safeInlineType(simplifyTypeForTable(param.type));
467
+ lines.push(`| \`${param.name}${opt}\` | ${typeCell} |`);
468
}
469
}
470
lines.push('');
@@ -477,10 +474,10 @@ function generateMethodMdx(method: MethodDoc): string {
474
if (sig.returnType !== 'void') {
475
lines.push('**Returns**');
476
lines.push('');
480
- const safeReturnType = escapeForMdx(simplifyTypeForTable(sig.returnType));
481
- let returnLine = `\`${safeReturnType}\``;
477
+ const returnTypeDisplay = safeInlineType(simplifyTypeForTable(sig.returnType));
478
+ let returnLine = returnTypeDisplay;
479
if (sig.returnDescription) {
483
- returnLine += ` — ${sig.returnDescription}`;
480
+ returnLine += ` — ${escapeTextForMdx(sig.returnDescription)}`;
481
}
482
lines.push(returnLine);
483
lines.push('');
@@ -571,16 +568,16 @@ function generateClassMdx(classDoc: ClassDoc): string {
568
lines.push('| Name | Type | Description |');
569
lines.push('|------|------|-------------|');
570
for (const prop of publicProps) {
574
- const safeType = escapeForMdx(simplifyTypeForTable(prop.type));
575
- const safeDesc = escapeForMdx(prop.description || '');
576
- lines.push(`| \`${prop.name}\` | \`${safeType}\` | ${safeDesc} |`);
571
+ const typeCell = safeInlineType(simplifyTypeForTable(prop.type));
572
+ const safeDesc = escapeTextForMdx(prop.description || '');
573
+ lines.push(`| \`${prop.name}\` | ${typeCell} | ${safeDesc} |`);
574
}
575
} else {
576
lines.push('| Name | Type |');
577
lines.push('|------|------|');
578
for (const prop of publicProps) {
582
- const safeType = escapeForMdx(simplifyTypeForTable(prop.type));
583
- lines.push(`| \`${prop.name}\` | \`${safeType}\` |`);
579
+ const typeCell = safeInlineType(simplifyTypeForTable(prop.type));
580
+ lines.push(`| \`${prop.name}\` | ${typeCell} |`);
581
}
582
}
583
lines.push('');
@@ -605,9 +602,28 @@ function toKebabCase(str: string): string {
602
.toLowerCase();
603
}
604
608
-// Escape curly braces for MDX (they're interpreted as JSX expressions)
609
-function escapeForMdx(str: string): string {
610
- return str.replace(/\{/g, '\\{').replace(/\}/g, '\\}');
605
+// Escape text content for MDX (descriptions, etc. that appear outside backticks)
606
+// Handles both curly braces and angle brackets (which MDX interprets as JSX tags)
607
+function escapeTextForMdx(str: string): string {
608
+ return str
609
+ .replace(/\{/g, '\\{')
610
+ .replace(/\}/g, '\\}')
611
+ .replace(/</g, '<')
612
+ .replace(/>/g, '>');
613
+}
614
+
615
+// Render a type string as an inline code element safe for MDX tables.
616
+// Uses <code> HTML tag with </> escaping instead of backticks,
617
+// because MDX parsers can interpret <TypeName> as JSX even inside
618
+// backtick code spans within table cells.
619
+function safeInlineType(type: string): string {
620
+ const escaped = type
621
+ .replace(/&/g, '&')
622
+ .replace(/</g, '<')
623
+ .replace(/>/g, '>')
624
+ .replace(/\{/g, '\\{')
625
+ .replace(/\}/g, '\\}');
626
+ return `<code>${escaped}</code>`;
627
}
628
629
// Clean up internal generic type parameters that don't add value for users
@@ -790,7 +806,7 @@ async function main() {
806
const classesTable = documented
807
.map(
808
({ name, description }) =>
793
- `| [\`${name}\`](/reference/sdk-reference/typescript/${toKebabCase(name)}) | ${escapeForMdx(description)} |`
809
+ `| [\`${name}\`](/reference/sdk-reference/typescript/${toKebabCase(name)}) | ${escapeTextForMdx(description)} |`
810
)
811
.join('\n');
812