@devries-cameron20 / composio-1 / commits / 4cd951390
Fork 0

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 &lt;/&gt; 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, '&lt;')
612 + .replace(/>/g, '&gt;');
613 +}
614 +
615 +// Render a type string as an inline code element safe for MDX tables.
616 +// Uses <code> HTML tag with &lt;/&gt; 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, '&amp;')
622 + .replace(/</g, '&lt;')
623 + .replace(/>/g, '&gt;')
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