MDX 处理

相关源文件

• apps/www/components/code-block-command.tsx
• apps/www/components/code-tabs.tsx
• apps/www/components/copy-button.tsx
• apps/www/components/mdx-components.tsx
• apps/www/content/docs/components/calendar.mdx
• apps/www/content/docs/components/carousel.mdx
• apps/www/content/docs/components/menubar.mdx
• apps/www/content/docs/components/navigation-menu.mdx
• apps/www/content/docs/components/progress.mdx
• apps/www/content/docs/components/scroll-area.mdx
• apps/www/content/docs/components/sonner.mdx
• apps/www/content/docs/components/table.mdx
• apps/www/content/docs/components/toast.mdx
• apps/www/hooks/use-config.ts
• apps/www/lib/rehype-component.ts
• apps/www/lib/rehype-npm-command.ts
• apps/www/types/unist.ts

本文档介绍了 shadcn/ui 文档系统中的 MDX 内容处理方式，包括 rehype 插件流程、自定义组件处理和代码块增强。这涵盖了将 Markdown 内容转换为具有实时组件预览和增强代码块的交互式文档的过程。

有关文档网站整体架构的信息，请参阅 文档网站。有关导航结构配置，请参阅 导航结构。

MDX 处理流程

MDX 处理系统通过一个多阶段流程，将 Markdown 内容转换为交互式文档，该流程包括 rehype 插件、自定义组件解析和增强的代码渲染。

来源： apps/www/components/mdx-components.tsx1-348 apps/www/lib/rehype-npm-command.ts1-99 apps/www/lib/rehype-component.ts1-283

核心 MDX 组件系统

Mdx 组件作为核心渲染器，将 MDX 元素映射到具有增强功能的 React 组件。

组件映射为标准 HTML 元素提供了增强的样式和功能

元素类型	增强功能	实现
标题（h1 - h6）	滚动边距，一致的排版	mdx-components.tsx53-106
代码块（pre）	复制按钮，语法高亮，包管理器支持	mdx-components.tsx183-235
行内代码	带样式的背景，等宽字体	mdx-components.tsx236-244
表格	响应式溢出，一致的样式	mdx-components.tsx148-182

来源： apps/www/components/mdx-components.tsx44-330 apps/www/components/mdx-components.tsx336-347

Rehype 插件系统

包管理器命令处理

rehypeNpmCommand 插件自动转换 npm 命令以支持多种包管理器

插件处理这些命令模式

• npm install → 转换为所有包管理器
• npx create- → 映射到 yarn create、pnpm create、bunx --bun
• npm create → 为每个包管理器直接对应
• npx (通用) → 映射到 pnpm dlx、bunx --bun
• npm run → 缩短为包管理器对应项

来源： apps/www/lib/rehype-npm-command.ts4-99

组件解析处理

rehypeComponent 插件通过读取注册表中的组件文件来处理 ComponentPreview 和 ComponentSource 元素

来源： apps/www/lib/rehype-component.ts10-264 apps/www/__registry__/index.tsx

代码块增强系统

多包管理器命令块

CodeBlockCommand 组件渲染带有交互式包管理器选项卡的命令块

来源： apps/www/components/code-block-command.tsx13-110 apps/www/hooks/use-config.ts1-25

复制按钮集成

复制功能贯穿整个文档，并带有事件跟踪

组件	复制目标	事件跟踪
CopyButton	原始代码字符串	copy_component_code
CopyNpmCommandButton	包管理器命令	copy_npm_command
CopyWithClassNames	组件或类名	无跟踪

来源： apps/www/components/copy-button.tsx24-207

自定义 MDX 组件

组件文档组件

MDX 系统包含用于文档化 UI 组件的专用组件

安装流程组件

CodeTabs 组件为 CLI 和手动安装提供统一的界面

来源： apps/www/components/code-tabs.tsx8-26 apps/www/components/mdx-components.tsx255-314

UnistNode 处理类型

MDX 处理系统使用类型化的 AST 节点进行安全转换

来源： apps/www/types/unist.ts1-32