Mastra 文档组件指南用共享 MDX 组件构建可被 llms-txt 提取的高质量技术文档【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra导读Mastra 官方文档站基于 Docusaurus MDX 构建文档内容中大量使用了CardGrid、IntegrationGrid、Steps、PropertiesTable、CopyPrompt、Inject等共享 React 组件。这些组件并非简单的样式封装它们编码了一套既定的文档编排与信息提取模式既要为人类读者提供一致的视觉与交互体验又要通过data-slot、data-llms-ignore等约定让 llms-txt 提取插件准确地把文档转成可被 AI 代理理解的纯文本结构。读完本文你将掌握 Mastra 仓库中每一类文档组件的适用场景、MDX 调用语法、关键参数语义以及它们与底层提取插件的协作原理从而写出既专业又对搜索引擎、Agent 和 LLM 友好的文档。本文以 docs/styleguides/COMPONENTS.md 为骨架结合 docs/src/components 下的组件源码与 docs/src/plugins/docusaurus-plugin-llms-txt 提取插件实现进行纵深讲解。为什么需要共享文档组件文档规范的开篇即给出核心原则当一种编排或提取模式已经被确立时就应该使用共享组件来编码它。在引入新的标记写法之前先查阅 docs/CONTRIBUTING.md 和现有页面中的实际用法。这条原则背后有两个直接原因一致性卡片边框、链接样式、栅格布局等视觉细节不应由每个页面手工重造共享组件保证所有页面行为一致。可提取性共享组件自带 llms-txt 提取所需的data-slot结构如card-grid、card、card-title页面只要正确使用组件提取插件就能稳定地把可视化卡片还原成 Markdown 链接列表。这一点在 组件源码 与 提取插件 中是成对设计、互相呼应的。CardGrid与CardGridItem精选目的地的卡片栅格适用场景CardGrid用于展示一组由当前页面自主决定的精选目的地——标签、描述和顺序都属于当前页面的内容语义。典型例子是文档首页的Agents、Workflows等功能入口卡片。基本用法import { CardGrid, CardGridItem } from site/src/components/cards/card-grid; CardGrid columns{3} CardGridItem titleAgents descriptionCreate model-powered agents. href/docs/agents/overview / /CardGrid源码级要点columns支持2 | 3 | 4默认值为2。源码中通过lg:grid-cols-2/3/4映射到响应式 Tailwind 栅格类移动端恒为单列、平板为两列见 card-grid.tsx。CardGridItem还支持logo字符串 URL 或 React 节点与preserveLogoColor参数。默认情况下 Logo 在暗色模式会被反白处理dark:invert设置preserveLogoColor{true}可保留原始配色见 card-grid.tsx。整个卡片渲染为包裹在Card中的链接视觉上呈现为圆角边框卡片hover 时背景色变化。重要约束不要手工重造卡片边框、链接或栅格布局。共享组件不仅提供视觉一致性更重要的是它输出了data-slotcard-grid容器这是 llms-txt 插件识别卡片栅格并抽取链接的关键契约详见下文llms-txt 控制一节。IntegrationGrid从侧边栏数据源驱动的集成卡片适用场景当条目来自集成侧边栏时应使用IntegrationGrid而不是CardGrid。侧边栏数据源位于docs/src/content/en/integrations/sidebars.js它始终是标签、路由、排序和图标的唯一事实来源——不要把这份元数据复制到 MDX 中。基本用法import { IntegrationGrid } from site/src/components/integrations/grid; IntegrationGrid sectionFrameworks allowlist{[frameworks/next-js, frameworks/astro]} /可用控制项参数语义section集成侧边栏的分类名category label例如Frameworksallowlist要包含的条目键列表按请求顺序输出支持排序控制blocklist要排除的条目键列表additionalItems侧边栏形状的补充条目用于没有独立集成页面的项columns三列默认或四列布局类型为3 \| 4源码级要点从 data.ts 可以看出其数据流组件从sidebars.js导入integrationsSidebar数据运行时按section找到对应分类若传了allowlist则按 allowlist 顺序flatMap查找条目未命中的键会被静默跳过否则输出该分类全部条目再追加additionalItems并统一按blocklist过滤注意一个细节当存在additionalItems时结果会按标签字母序排序localeCompare这解释了为什么 allowlist 的顺序控制仅在受支持时生效。图标方面grid.tsx 的IntegrationIcon会读取条目customProps中的icon与iconDark若提供了暗色图标则通过dark:hidden/hidden dark:block分别在明暗模式下切换未提供则复用同一张图标。Steps与StepItem有顺序的操作步骤适用场景只有当读者必须按顺序完成一系列动作且每个动作需要较多文字、代码或提示块来支撑时才使用Steps。若是简短步骤直接用 Markdown 有序列表即可。不要仅仅为了让不相关的章节看起来像操作流程而滥用Steps——这会误导读者对执行顺序的认知。基本用法import Steps from site/src/components/Steps; import StepItem from site/src/components/StepItem; Steps StepItem ### Install the package bash npm2yarn npm install mastra/core /StepItem StepItem ### Configure the agent Add your model provider configuration here. /StepItem /Steps源码级要点Steps本质是渲染为ol列表Steps.tsxStepItem渲染为liStepItem.tsx样式由Steps.module.css提供。语义 HTML 结构保证了对屏幕阅读器和 llms-txt 提取都友好。Tabs与TabItem互斥的替代方案适用场景Tabs用于互斥的备选方案例如不同的包管理器npm/pnpm/yarn、运行时、框架或后端选择。共享的安装/配置步骤应放在 Tabs之外避免重复。反模式不要把顺序执行的步骤藏进 Tabs——用户可能看不到后续步骤当读者需要同时对比两个示例时不要使用 Tabs——此时应并排展示两个完整示例。基本用法import Tabs from theme/Tabs; import TabItem from theme/TabItem; Tabs TabItem valuenpm labelnpm default bash npm install mastra/core /TabItem TabItem valuepnpm labelpnpm bash pnpm add mastra/core /TabItem /Tabs提取机制补充Tabs 在 llms-txt 提取时并非被丢弃而是由插件转换为标签名加粗 面板内容的段落序列插件先读取roletablist中的标签文本再逐一对齐roletabpanel的内容输出形如**npm**:后跟内容的格式见 component-handlers.ts。这意味着 Tabs 的互斥内容不会被静默丢弃而是被保留为带标签的文本块。PropertiesTable结构化 API 参数表适用场景用于展示结构化的 API 参数、属性、配置项和嵌套类型——例如函数/方法/构造器的参数与返回类型。编写时以现有 reference 页面的对象形状为参照。基本用法PropertiesTable content{[ { name: options, type: RunOptions, description: Options for the run., properties: [ { type: RunOptions, parameters: [ { name: timeout, type: number, description: Timeout in milliseconds., isOptional: true, }, ], }, ], }, ]} /对象形状说明每个content数组元素支持name参数名渲染时带:或?:后缀表示是否可选type参数的数据类型isOptional是否可选可选时显示为name?:description参数描述内部支持行内 Markdown——源码中用正则拆分并渲染反引号代码与text链接见 PropertiesTable.tsxdefaultValue默认值渲染为 默认值前缀properties嵌套参数组内含type与parameters数组。嵌套组在 UI 上以独立边框区块呈现并标出所属类型如RunOptions。嵌套参数的渲染语义规范特别强调嵌套参数组要把parameters放在带type的条目内部。源码中properties数组的每一项渲染为一个带类型标签的嵌套区块区块内的每个参数行有自己的name、type、description且支持无限递归嵌套PropertiesTable.tsx。提取机制补充llms-txt 插件对PropertiesTable有专门处理器它通过data-testidproperties-table、property-row、property-name、property-type、property-default、property-description定位每个字段输出为定义列表格式**name** (\type): description (Default: value)嵌套字段会以点号前缀展开为parent.child见 component-handlers.ts。CopyPrompt可复制的 AI 编码提示词适用场景当页面提供一个自包含的提示词供 AI 编码工具使用例如请按照本文档实现某个 Agent时使用CopyPrompt。提示词应指明预期结果、相关文件与约束条件。使用注意不要把它当作人类可读指令的替代品。页面正文必须对人类读者保持完整CopyPrompt只是方便复制到 AI 工具中的一个附加封装。源码级要点copy-prompt.tsx 的实现揭示了它的工作机制折叠面板 Copy prompt 按钮点击后调用navigator.clipboard.writeText写入剪贴板并短暂显示 Copied! 反馈带aria-livepolite的无障碍状态提示复制内容并非直接取 DOM 文本而是通过getNodeText递归遍历 React 节点树做结构化还原p/div段落转双换行、pre转围栏代码块、code转行内反引号、li转-列表项见 copy-prompt.tsx复制前会用normalizePromptText压缩多余空行、去除行尾空白并trim见 copy-prompt.tsx复制事件会通过vercel/analytics的track(docs-copy_prompt, { identifier })上报identifier参数用于区分不同页面的提示词。Inject仅面向 AI 代理的隐藏指令适用场景Inject用于放置简短且关键的指令专门帮助 AI 代理正确应用周围的文档内容。它的渲染结果是隐藏的人类读者在页面上看不到但会进入 llms-txt 提取产物中。使用注意正常页面内容必须对人类读者保持完整。Inject只是补充性的代理指令不能把正文挪进其中。源码级要点inject.tsx 的实现非常简洁渲染为div>:::note Some **content** with _Markdown_ syntax. Check [this api](#). ::: :::warning Some **content** with _Markdown_ syntax. ::: :::danger Some **content** with _Markdown_ syntax. ::: :::beta Some **content** with _Markdown_ syntax. :::两条铁律不要把常规操作步骤放进 admonition——步骤应有正常的文档流程admonition 只承载需要强调的附注性信息betaadmonition 只能用于明确以 Beta 呈现的功能不要用它来标记新功能或实验性等泛化语义。实战检查清单写作一个新文档页面时可对照以下清单快速决策页面上有一组目的地入口卡片→ 条目由本页定义用CardGridCardGridItem条目来自集成侧边栏用IntegrationGrid。读者需要按顺序完成操作且每步内容较多→StepsStepItem步骤很短则直接用有序列表。内容是互斥的备选方案包管理器、运行时→TabsTabItem共享步骤放外面需要并排对比则不用 Tabs。需要展示函数/方法参数、配置项或嵌套类型→PropertiesTable嵌套参数用带type的properties结构。页面提供一个给 AI 编码工具的自包含提示词→CopyPrompt同时保持正文对人类的完整性。需要给 AI 代理补充执行上下文但不想打扰人类读者→Inject。页面包含交互控件文本或自绘卡片标记→ 控件加data-llms-ignore卡片保留data-slot三件套优先语义 HTML。有需要强调的风险、兼容性或 Beta 信息→ 按语义选择note/warning/danger/beta。修改了提取相关的标记→ 运行 llms-txt 插件测试确认提取产物正确。最后提醒在动手引入任何新的标记写法之前先翻一遍 docs/styleguides/COMPONENTS.md、docs/CONTRIBUTING.md 以及现有页面的实际用法——共享组件的意义就在于一次设计、处处复用、可被稳定提取而不是每个页面各自发明一套 UI 方言。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考