Mastra 文档组件体系用共享 MDX 组件构建可提取、可检索的技术文档【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra导读本文基于 Mastra 仓库中的文档组件规范.claude/skills/mastra-docs/references/COMPONENTS.md系统讲解 Mastra 文档站位于 docs 目录如何通过CardGrid、IntegrationGrid、PropertiesTable、CopyPrompt、Inject等共享 MDX 组件把人类阅读体验与llms-txt 机器提取统一在同一套标记体系中。读完本文你将掌握 Mastra 文档组件的使用场景、正确写法、底层实现原理以及如何为 AI Agent / LLM 编写可被准确提取与检索的文档页面。文档组件的设计初衷一处编码两处消费Mastra 的文档站点基于 Docusaurus MDX 构建内容目录在 docs/src/content/en。它有一个特殊的约束同一份 MDX 页面既要给人类读者呈现精美的交互界面卡片、标签页、步骤、参数表又要被 docs/src/plugins/docusaurus-plugin-llms-txt 这类提取插件处理成结构化文本llms.txt / llms-full.txt供搜索引擎、Agent 与 LLM 消费。因此规范的第一条原则是当组件编码了一种既定的文档模式或提取模式时优先使用共享组件。在引入新的标记写法前先查看 docs/CONTRIBUTING.md 和现有页面的实际用法。换句话说共享组件承担两个职责其一提供一致的视觉与交互行为边框、链接、栅格布局、可访问性其二暴露稳定的data-slot、data-llms-ignore等提取钩子让 llms-txt 生成管线能够精确还原内容结构。CardGrid与CardGridItem受控的卡片目的地集合使用场景与写法CardGrid用于展示一组由当前页面决定标签、描述与顺序的精选目的地destination。所谓由当前页面决定意味着这些卡片的内容元数据直接写在 MDX 里而不是从某个全局配置中读取import { CardGrid, CardGridItem } from site/src/components/cards/card-grid; CardGrid columns{3} CardGridItem titleAgents descriptionCreate model-powered agents. href/docs/agents/overview / /CardGrid规范明确要求不要手工复刻卡片边框、链接或栅格布局。原因在于共享组件提供了两样手工实现难以复制的东西一致的视觉行为圆角、悬浮态、明暗主题适配供 llms-txt 提取的 card-grid 数据槽位。源码级实现CardGrid与CardGridItem的实现位于 docs/src/components/cards/card-grid.tsx。关键点如下CardGrid接受columns属性取值2 | 3 | 4默认2内部通过lg:grid-cols-*的 Tailwind 类实现响应式栅格移动端单列、平板双列、桌面端按columns分列并渲染data-slotcard-grid供提取插件识别见 card-grid.tsx。CardGridItem接受title、description、href、可选的logo字符串 URL 或 React 节点与preserveLogoColor若传入了字符串logo在暗色主题下默认做反色处理dark:invert如需保留原始品牌色则设置preserveLogoColor见 card-grid.tsx。渲染时整个卡片是一个指向href的 DocusaurusLink描述内容只有在存在children || description时才渲染保证仅标题卡片与带描述卡片的视觉一致性。实际页面中的典型案例是 docs/src/content/en/docs/auth/overview.mdx它用CardGrid组织 JWT、OAuth 等认证方案的入口卡片并用IntegrationGrid sectionAuth展示集成列表。IntegrationGrid以侧边栏为唯一事实来源的集成网格使用场景当需要展示的条目来源于集成文档侧边栏即 docs/src/content/en/integrations/sidebars.js时使用IntegrationGrid而非手工编写卡片import { IntegrationGrid } from site/src/components/integrations/grid; IntegrationGrid sectionFrameworks allowlist{[frameworks/next-js, frameworks/astro]} /可用控制项控制项作用section集成侧边栏中的分类名category label决定从哪个分类取条目allowlist要包含的条目键key列表在支持的情况下按请求顺序排列blocklist要排除的条目键列表additionalItems侧边栏形状的补充条目用于那些没有独立集成页的项columns三列或四列布局3 \| 4默认3核心设计原则是集成侧边栏始终是标签、路由、排序与图标的唯一事实来源不要把这份元数据复制进 MDX 页面。这样新增、改名、排序一个集成时只需改一处。源码级实现IntegrationGrid的实现位于 docs/src/components/integrations/grid.tsx数据逻辑在 docs/src/components/integrations/data.tsdata.ts 从sidebar.integrationsSidebar读取原始侧边栏经运行时类型守卫isIntegrationCategory/isIntegrationItem过滤出合法分类与条目防止运行时数据结构异常导致渲染崩溃。getIntegrationItems的核心逻辑见 data.ts先按section找到分类若提供了allowlist则按 allowlist 顺序在分类条目中查找匹配项allowlist.flatMap(...)未命中的键被静默跳过随后追加additionalItems再统一剔除blocklist命中的条目。注意一个细节只有存在additionalItems时最终列表才会按标签字母序排序localeCompare否则保持侧边栏原始顺序——这解释了为什么allowlist 顺序优先只在无补充条目时成立。渲染层见 grid.tsx输出语义化的ul/li列表每个条目渲染data-slotcard-grid、data-slotcard与data-slotcard-title并使用getIntegrationItemHref统一生成/integrations/${item.id}路由doc类型条目取id作为 keylink类型条目取href作为 key。图标支持浅色 / 深色双图customProps.icon与customProps.iconDark暗色主题自动切换见 grid.tsx。配套的 docs/src/components/integrations/data.test.ts 与 docs/src/components/integrations/page.tsx 分别验证了数据过滤逻辑与集成列表页的渲染方式可作为理解该组件行为的测试证据。Steps与StepItem真正需要按序执行的步骤Steps/StepItem用于**读者必须按顺序完成、且每一步都需要大段说明文字、代码或警示块**的操作序列。如果步骤很短直接用 Markdown 有序列表即可。import { Steps, StepItem } from site/src/components/Steps; Steps StepItem 第一步的详细说明…… /StepItem StepItem 第二步的详细说明…… /StepItem /Steps规范特别强调一个反模式不要仅仅为了让无关小节看起来像流程而使用Steps。实现上Steps.tsx 渲染一个带rolelist的ol配合 Steps.module.css 的样式StepItem.tsx 渲染li保证顺序语义在无障碍与提取场景下都成立。Tabs与TabItem互斥选项才用标签页Tabs用于互斥的备选方案例如包管理器npm / pnpm / yarn、运行时、框架或后端选型import Tabs from theme/Tabs import TabItem from theme/TabItem Tabs TabItem valuenpm labelnpm default 使用 npm 安装…… /TabItem TabItem valuepnpm labelpnpm 使用 pnpm 安装…… /TabItem /Tabs两条硬性规则共享的前置步骤放在标签页外面——读者不应为了看到建目录这类公共步骤而被迫点开某个标签不要把顺序执行的多步指令藏在标签页里也不要为了读者需要同时对比两个例子的场景使用标签页——需要对比时请并排展示而不是隐藏。Mastra 文档对npm install代码块还有一种约定使用bash npm2yarn标记后站点会自动生成包管理器切换开关详见 docs/CONTRIBUTING.md。PropertiesTable结构化 API 参数与嵌套类型使用场景PropertiesTable用于在参考reference类页面中展示函数、方法或构造函数的参数与返回类型。它支持 Markdown 风格的code与链接内联渲染见 PropertiesTable.tsx并能递归渲染嵌套参数组。顶层条目的基本形状PropertiesTable content{[ { name: id, type: string, isOptional: true, description: Unique identifier for the agent. Defaults to name if not provided., }, ]} /字段说明name参数或返回项的名称type数据类型isOptional是否可选布尔值默认false渲染为name?:形式description简要描述defaultValue可选渲染为 默认值形式见 PropertiesTable.tsxproperties嵌套参数组嵌套参数组的写法当某参数本身是复合对象时把parameters放进一个带type的properties条目中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, }, ], }, ], }, ]} /从实现看PropertiesTable.tsx嵌套组会以独立边框卡片渲染type以角标形式悬浮在卡片右上角每个参数行带data-testidproperty-row、property-name、property-type、property-description等测试钩子便于快照测试与提取插件解析。isOptional决定名称后渲染?:还是:。CopyPrompt为 AI 编码工具准备的一键复制提示词当页面提供一个自包含、可直接交给 AI 编码工具执行的提示词时使用CopyPrompt。它把大段提示词折叠起来读者点击展开、一键复制import { CopyPrompt } from site/src/components/copy-prompt; CopyPrompt identifierbuild-agent-from-scratch 构建一个名为 support-agent 的 Mastra Agent文件位于 src/mastra/agents 使用 mastra/core 的 Agent 类模型使用 openai:gpt-4o并暴露 getWeather 工具…… /CopyPrompt规范要求提示词本身说清楚预期结果、相关文件与约束条件同时强调它不能替代给人类读者阅读的正常说明——页面正文必须保持完整可读。源码实现copy-prompt.tsx值得注意getNodeText递归提取 React 子树为纯文本p/div转成空行分隔、pre转成围栏代码块、code转成反引号行内码、li转成-列表项见 copy-prompt.tsxnormalizePromptText会折叠多余空行、去掉行尾空白见 copy-prompt.tsx保证复制出的提示词干净可用点击复制通过navigator.clipboard.writeText实现复制成功后按钮短暂显示 Copied!并调用 Vercel Analytics 的track(docs-copy_prompt, { identifier })统计该提示词的复制行为见 copy-prompt.tsx——identifier属性正是用于埋点区分不同提示词。Inject写给 AI Agent 的隐形指令Inject用于插入简短、关键、专门帮助 AI Agent 应用周边文档的指令同时在 UI 上完全不可见。它解决的是同一页面服务两类读者的矛盾人类读者看到的是正常完整页面Agent 在提取时额外获得一份怎么用这份文档的说明。import { Inject } from site/src/components/inject; Inject 当你要修改该 Agent 的模型配置时请同时更新本页 src/mastra/agents/index.ts 中的 model 字段与 docs 中的对应参考页。 /Inject实现位于 inject.tsx渲染一个style{{ display: none }}、aria-hiddentrue的div并带有data-midinject标记。UI 不展示、无障碍树隐藏但 llms-txt 提取管线可以按标记捞取内容——这也再次印证了 Mastra 文档双通道消费的设计。在 docs/src/content/en/docs/agents/overview.mdx、agents/structured-output.mdx、agents/tools.mdx 等页面中都能看到Inject的实际用例。llms-txt 提取控制让机器可读性与组件规范同步Mastra 的文档体系对AI 可检索性是一等公民这部分是编写共享组件时必须遵守的提取契约data-llms-ignore添加到那些不应出现在提取文档中的渲染控件或界面文本上。例如纯粹的交互按钮文案、装饰性标签——这些对人类有用但对文本提取是噪音。保留提取槽位在扩展被 llms-txt 插件识别的卡片标记时必须保留data-slotcard-grid、data-slotcard与data-slotcard-title。这三个槽位分别标识网格容器、单张卡片与卡片标题是插件还原卡片语义的依据。正如前文所见CardGrid与IntegrationGrid的实现都严格遵循了这一约定。优先语义化 HTML当内容能用ul/li准确表达时优先使用语义化列表而不是 div 堆砌——语义标签让提取器无需猜测结构。改动后必须测试任何涉及提取感知标记extraction-aware markup的改动都要跑一遍生成逻辑并检查生成结果。插件本体位于 docs/src/plugins/docusaurus-plugin-llms-txt其中 component-handlers.ts 与 html-processor.ts 负责组件与 HTML 的处理tests下有component-handlers.test.ts与content-extractor.test.ts等测试来锁定提取行为。这些测试正是改动提取标记后必须验证这一规范的落地保障。Admonitions警示块值得视觉隔离的信息才用Admonitions 用于值得与正文视觉分离的信息Mastra 使用:::label语法:::note 作用域、兼容性或补充性上下文。 ::: :::warning 可能的失败模式、安全关注点或破坏性后果。 ::: :::danger 严重且迫在眉睫的风险。 ::: :::beta 明确以 Beta 呈现的功能特性。 :::四种类型的语义定位类型适用内容note作用域说明、兼容性说明、补充性上下文info是note的别名渲染相同优先用notewarning可能的失败模式、安全隐患或破坏性后果danger严重且迫在眉睫的风险beta仅用于明确以 Beta 呈现的功能两条红线不要把常规操作步骤塞进 admonition步骤应该用正文或Stepsbetaadmonition 只允许用于官方标记为 Beta 的功能不能用来暗示这是新东西。组合使用从规范到页面的决策路径综合全文编写一个 Mastra 文档页面时的组件选型可以概括为如下决策路径要展示一组目的地/入口内容元数据属于本页 →CardGrid条目来自集成侧边栏 →IntegrationGrid元数据以侧边栏为准。要呈现操作流程必须按序执行且每步内容多 →Steps/StepItem步骤短 → Markdown 有序列表互斥备选方案 →Tabs。要列出 API 参数/返回类型结构化、可嵌套 →PropertiesTable。要给 AI 编码工具提供自包含提示词→CopyPrompt同时保留完整的人类可读正文。要悄悄给 AI Agent 补充应用文档的指令→Inject。要强调某类信息→ 按note/warning/danger/beta语义选择合适的 admonition。任何情况下遵守data-llms-ignore与data-slot提取契约改动提取感知标记后运行 llms-txt 生成并检查产物。这套规范的价值在于它把写文档从一次性的排版劳动变成了可持续演进的内容基础设施——人类读者获得一致的界面与可访问性AI 读者获得稳定、语义明确、可测试的结构化提取结果。无论是新增页面还是维护既有文档遵循 .claude/skills/mastra-docs/references/COMPONENTS.md 与 docs/CONTRIBUTING.md 中的约定就能让文档在两类读者面前都保持高质量。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考