fix: escape curly braces in generated MDX docs#601
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
The getFileDescription() function in build-docs.ts now escapes { and }
characters in extracted JSDoc text, preventing MDX from interpreting
them as JSX expressions. Regenerated all affected MDX docs.
Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>
|
@copilot 确认一下这个文件是不是是用脚本自动生成的？ |
是的， 流程： 具体来说， |
There was a problem hiding this comment.
Pull request overview
Fixes MDX build failures caused by unescaped {} in file-level JSDoc descriptions being inserted into generated reference docs (MDX parses {} as JSX/expressions).
Changes:
- Updated
getFileDescription()inpackages/spec/scripts/build-docs.tsto escape{and}in extracted JSDoc. - Regenerated reference MDX pages so curly braces in extracted descriptions no longer break the docs build.
Reviewed changes
Copilot reviewed 21 out of 21 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| packages/spec/scripts/build-docs.ts | Escapes curly braces in extracted JSDoc descriptions to prevent MDX JSX parsing errors. |
| content/docs/references/ui/widget.mdx | Regenerated docs; code examples now include escaped braces. |
| content/docs/references/system/worker.mdx | Regenerated docs; code examples now include escaped braces. |
| content/docs/references/system/translation.mdx | Regenerated docs; code examples now include escaped braces. |
| content/docs/references/system/notification.mdx | Regenerated docs; template/code examples now include escaped braces. |
| content/docs/references/studio/plugin.mdx | Regenerated docs; TS example braces now escaped. |
| content/docs/references/shared/mapping.mdx | Regenerated docs; TS example braces now escaped. |
| content/docs/references/security/rls.mdx | Regenerated docs; TS example braces now escaped. |
| content/docs/references/kernel/execution-context.mdx | Regenerated docs; usage snippet braces now escaped. |
| content/docs/references/data/validation.mdx | Regenerated docs; TS example braces now escaped. |
| content/docs/references/data/external-lookup.mdx | Regenerated docs; JSON example braces now escaped. |
| content/docs/references/data/document.mdx | Regenerated docs; JSON example braces now escaped. |
| content/docs/references/automation/trigger-registry.mdx | Regenerated docs; TS example braces now escaped. |
| content/docs/references/automation/sync.mdx | Regenerated docs; TS example braces now escaped. |
| content/docs/references/automation/etl.mdx | Regenerated docs; TS example braces now escaped. |
| content/docs/references/api/registry.mdx | Regenerated docs; TS example braces now escaped. |
| content/docs/references/api/plugin-rest-api.mdx | Regenerated docs; JSON example braces now escaped. |
| content/docs/references/api/odata.mdx | Regenerated docs; TS example braces now escaped. |
| content/docs/references/api/graphql.mdx | Regenerated docs; GraphQL example braces now escaped. |
| content/docs/references/api/documentation.mdx | Regenerated docs; TS example braces now escaped. |
| content/docs/references/ai/devops-agent.mdx | Regenerated docs; TS example braces now escaped. |
| .replace(/\{@link\s+([^|]+?)\s*\|\s*([^}]+?)\s*\}/g, '[$2]($1)') // {@link url | text} -> [text](url) | ||
| .replace(/\{@link\s+([^}]+?)\s*\}/g, '[$1]($1)') // {@link url} -> [url](url) | ||
| .replace(/file:\/\//g, '') // Remove file:// protocol | ||
| .replace(/\{/g, '\\{').replace(/\}/g, '\\}') // Escape { } for MDX |
There was a problem hiding this comment.
The new global {/} escaping runs across the entire extracted JSDoc, including fenced code blocks. In MDX, braces inside triple-backtick code fences are already safe, so this change makes generated examples render with literal backslashes and breaks copy/paste (e.g. GraphQL/TS object literals become \{ ... \}). Consider escaping braces only in non-code segments (outside fenced code blocks, and ideally outside inline backticks as well), so MDX build errors are fixed without degrading code samples.
Vercel docs build fails on
execution-context.mdxbecausegetFileDescription()extracts JSDoc containing{ context: { userId: '...' } }and inserts it as raw MDX, where{}are parsed as JSX expressions.packages/spec/scripts/build-docs.ts: Escape{→\{and}→\}ingetFileDescription()after{@link}tag processing✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.