Mastra 文档页面风格指南：从页面类型到 MDX 结构的完整写作规范

Mastra 文档页面风格指南从页面类型到 MDX 结构的完整写作规范【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra导读本文基于 Mastra 仓库的 docs/styleguides/DOC.md 展开系统讲解 Mastra 官方产品文档位于docs/src/content/en/docs的页面分类、内容组织方式与 MDX 骨架写法。文中同时结合 docs/styleguides/STYLEGUIDE.md、docs/styleguides/COMPONENTS.md、docs/styleguides/INFORMATION_ARCHITECTURE.md 等配套规范并引入仓库中 docusaurus-plugin-llms-txt 的实现细节说明页面结构与组件标记如何影响 llms.txt 抽取。读完本文你可以掌握 Mastra 文档各页面类型的适用场景、推荐结构、frontmatter 写法与组件选用规则直接用于撰写或评审仓库内的文档页面。页面类型五种写作模式DOC.md 明确指出docs/src/content/en/docs下的大多数文档页面都符合以下五种模式之一。它们是写作模式authoring patterns而非强制模板当结果仍然自洽时一页可以组合多种模式。页面类型用途典型场景Overview定义一个类别、解释重要选择、把读者引导到聚焦材料agents、memory、authentication、deployment、storage 等类别落地页Focused concept解释一个连贯的能力、行为或心智模型单个功能页、概念页Setup / configuration帮助读者启用并配置一个 Mastra 拥有的功能配置向导类页面Task-oriented把读者从已知起点带到可验证的结果操作指南、快速入门分类的核心判断依据是页面帮读者完成什么而不是页面长得像什么。一个任务导向页面既可以放在/docs也可以放在/integrations具体归属取决于内容的所有权见后文信息架构一节。Overview 页面用途与必备内容Overview 页面用于 agents、memory、authentication、deployment、storage 这类类别的落地页。一份合格的 Overview 应当定义类别包含什么、不包含什么define what the category includes and excludes解释主要的选择项或子主题explain the main choices or subtopics帮助读者决定从哪开始链接到最有用的聚焦页面和参考材料包含类别级约束或前置条件当立即可用的 setup 有助于读者理解类别时提供一条简短的可行路径。DOC.md 特别提醒不要把 Overview 变成所有子页面的副本。如果侧边栏或聚焦索引已经提供了穷尽式导航Overview 不需要链接每一个页面。可用的结构元素能力清单a short list of capabilities决策表a decision table用于精选目的地的CardGrid用于供应商选择的IntegrationGrid架构图或架构说明a diagram or architecture explanation快速入门a quickstart简短的类别级小节。建议骨架DOC.md 给出了 Overview 的标准 MDX 骨架--- title: $CATEGORY description: What the category helps readers understand or accomplish. packages: - mastra/core --- # $CATEGORY State what the category does and the main decision the page helps readers make. ## Choose an approach Explain the important options with a table, list, cards, or integration grid. ## Quickstart Include this only when a short working example clarifies the category. ## Category-wide topic Add sections for behavior shared across the category. ## Next steps Add selected follow-up links when they improve navigation.标题应直接使用清晰且已确立的类别名不要为了凑某种公式而添加后缀。Focused concept 页面用途与必备内容当读者需要一个连贯的解释或一项能力时使用聚焦页面。它应该说明概念是什么、为什么重要当读者面临真实选择时解释何时使用它当代码或配置属于概念的一部分时展示用法覆盖相关行为、约束和权衡tradeoffs对穷尽式选项链接到精确的 API 参考页面。DOC.md 建议即使页面超过三个 H2 小节也把相关小节放在一起只有当各小节有独立受众、独立任务或独立的内容所有权时才拆分为多个页面。建议骨架--- title: $FEATURE | $CATEGORY description: What the reader will understand or accomplish. packages: - mastra/core --- # $FEATURE Define the feature and its role in Mastra. ## When to use $FEATURE Add this section only when readers need help choosing it. ## Configure $FEATURE Introduce the example and show the supported setup. typescript titlesrc/mastra/path.ts // Complete code for the documented behaviorBehavior or constraintExplain the important runtime behavior, decision, or limitation.RelatedAdd selected links when they help readers continue.标题通常遵循 $FEATURE | $CATEGORY 模式但要以该栏目已有的标题模式为准H1 应直接命名主题对象。 ## Conceptual 页面 概念页可以比较模式、解释架构、建立术语**不一定要给 quickstart**。DOC.md 给出的组织原则 - 围绕读者的疑问和决策来组织Organize around reader questions and decisions - 用示例澄清概念而不是把页面硬塞进教程形式 - 直接陈述权衡State tradeoffs directly - 读者需要比较选项时用表格 - 在解释完模型之后再链接到实现页面和参考资料。 ## Setup 与 configuration 页面 配置类页面有三个硬性要求 - 从**受支持的配置方式**开始Start with the supported setup - 当默认值和持久化边界影响行为时解释它们Explain defaults and persistence boundaries when they affect behavior - 把**本地开发假设**与**生产环境要求**分开Separate local development assumptions from production requirements。 ## Task-oriented 页面 当页面主要目的是创建、配置、运行或排查一个 Mastra 拥有的能力时使用任务导向页面。DOC.md 要求应用 [STYLEGUIDE.md](https://link.gitcode.com/i/6908dac855cc0831e9a6c115210494a3) 中的任务序列task sequence并且**只使用任务需要的小节**不要为了套模板强加章节。 ### Quickstarts 的特殊规则 Quickstart 是聚焦于达成可用结果的最快受支持路径的短任务页或短节 - **优先使用仓库默认值**而不是解释每一个选择Prefer repository defaults over explaining every choice - 说明生成的命令或文件会创建什么State what generated commands or files create - 概念解释保持简短并链接到更深的文档。 这与仓库中的 [getting-started](https://link.gitcode.com/i/6d518199f82e8bb848e1242bb355c060) 目录的组织思路一致快速入门保持最短路径把完整解释放到聚焦页面。 ## 写作与组件配套规范 DOC.md 是页面级规范它与仓库中其他 styleguide 文件配套使用。写作时应同时参考 - [STYLEGUIDE.md](https://link.gitcode.com/i/6908dac855cc0831e9a6c115210494a3)默认写作指南规定语气、句式、标题、列表、代码示例格式。核心规则包括以读者的问题或任务组织页面而非强制模板、验证技术主张需对照实现、公开类型、包导出和测试、确认导入路径、选项名、默认值、返回值、环境变量和版本要求。它明确要求避免 AI 写作痕迹词汇如 delve、leverage、robust使用 Ensure 而非 make sure页面标题用 sentence case。 - [COMPONENTS.md](https://link.gitcode.com/i/27bc102ef68a1958f92d630c1fc563f2)共享组件规范定义了 CardGrid、IntegrationGrid、Steps、Tabs、PropertiesTable、CopyPrompt、Inject 及 admonitionnote / warning / danger / beta的适用场景。例如 Tabs 用于互斥的替代方案包管理器、运行时、框架不要把顺序执行的步骤藏进 tabs。 - [REFERENCE.md](https://link.gitcode.com/i/9bf435792314d1850419eaafa8cb24c1)适用于 docs/src/content/en/reference 下的 API、配置、CLI、类型查找页规定参数表格用 PropertiesTable、方法标题用反引号签名如 ### methodName(value, options?) 、CLI 参考必须包含语法、参数、默认值、环境变量和副作用。 - [GUIDE_INTEGRATION.md](https://link.gitcode.com/i/58b57988ba56aa26c4241e3f8603e77c)适用于 docs/src/content/en/integrations 下所有集成页按 Frameworks、Channels、Databases、Observability、Authentication、Browser 等类别给出常见覆盖范围并为部署集成页规定了 deployer 包、平台约束、安全与验证要求。 ### 与 llms-txt 抽取的联动 COMPONENTS.md 专门开辟了 llms-txt controls 一节这并非孤立的写作建议仓库中 [docusaurus-plugin-llms-txt](https://link.gitcode.com/i/db45d840ca4e4cd64fe817049cf9df5a) 插件是它的实现载体。从插件源码结构看[component-handlers.ts](https://link.gitcode.com/i/561bb04182797bdb23b9341be9963522)、[content-extractor.ts](https://link.gitcode.com/i/73d342b8ae863b8e13fa7ed8823c12a9)、[head-link.ts](https://link.gitcode.com/i/251fa7988e25af6d4288f14197c2ec54)该插件负责从渲染后的 HTML 抽取文档内容生成 llms.txt - 用 data-llms-ignore 标记不应出现在抽取文档中的渲染控件或界面文本 - 保留 data-slotcard-grid、data-slotcard、data-slotcard-title 等数据槽位供卡片标记被 llms-txt 插件识别 - 当内容能准确表达语义时优先使用语义 HTML含 ul、li - 修改抽取感知的标记后需要测试生成的节。 这意味着文档页面在选用卡片组件、编写 MDX 时不仅是排版问题还直接决定 LLM 与搜索引擎能从 llms.txt 中读到什么。组件测试文件如 [component-handlers.test.ts](https://link.gitcode.com/i/8091c41eea558a05f924c445aaad0898)、[content-extractor.test.ts](https://link.gitcode.com/i/859f9a5e1cb5cdac644451743efe4401)即为这些行为提供了可验证的用例证据。 ## 内容归属先选对位置再动笔 在动笔之前[INFORMATION_ARCHITECTURE.md](https://link.gitcode.com/i/e88728ad72ac8fe781b0e9d18e5c364c) 要求先决定内容的 canonical 归属canonical home。该规范定义了四类内容族 | 内容族 | 源目录 | 用途 | | --- | --- | --- | | /docs | docs/src/content/en/docs | Mastra 概念、能力、配置、决策和聚焦用法 | | /integrations | docs/src/content/en/integrations | 外部产品、供应商、框架、渠道和部署目标 | | /reference | docs/src/content/en/reference | API、配置、CLI、类型和查找材料 | | /models | docs/src/content/en/models | 生成的模型与供应商信息不要手动编辑 | 归属判断标准是**谁拥有这个概念或读者的决策** - Mastra 拥有概念agents、workflows、memory、storage、Studio、认证、部署概念→ /docs - 主要解释 Mastra 如何与外部产品协同框架、数据库、可观测性导出器、渠道、浏览器供应商、认证供应商、部署平台→ /integrations - 读者需要精确签名、选项、返回值、事件、命令或类型细节 → /reference并链接到 /docs 页面做概念解释而不是重复它。 在新建页面之前规范要求先在**所有内容族**中搜索该概念及其旧名称找出应该保持 canonical 的页面把缺失信息补到那个页面而不是在侧边栏的另一个合理分类下再造一个平行页面。 ## 页面维护与验证工作流 DOC.md 管怎么写[AUTHORING_WORKFLOW.md](https://link.gitcode.com/i/98c791cce43b58989fffb2f63ab91ef4) 管怎么改。它提供了从准备、移动、删除到验证的完整流程 - **移动页面**在 docs/ 下运行仓库脚本 pnpm tsx scripts/move-doc.ts /docs/old-route /docs/new-route支持 --dry-run脚本会更新侧边栏 ID、入站链接和重定向 - **删除或合并页面**运行 pnpm tsx scripts/delete-doc.ts /docs/old-page /docs/replacement - **维护重定向**vercel.redirects.json 是手工维护的权威来源vercel.json 是生成物改动后运行 pnpm generate-vercel-redirects生成器会拒绝重复源、拒绝重定向链并生成合格的 /llms.txt 伴生重定向 - **最小验证矩阵**纯文字 MDX 只需 MDX 格式、Remark 和 Vale 检查frontmatter 改动加 pnpm validate侧边栏改动加 build移动或删除需脚本测试、重定向、验证和 buildMDX 组件或 llms-txt 处理器改动需要聚焦的 Vitest 测试。 docs/ 目录下常用命令为 bash pnpm format:mdx:check pnpm format:check pnpm lint:remark pnpm lint:vale:ai pnpm validate pnpm test pnpm build其中生产构建pnpm build是验证路由解析、MDX 编译和生成的 llms-txt 输出的最终证明。结合源码审视文档规范的实际落地DOC.md 描述的是规范仓库本身即为规范的活样本内容族目录确实按规范组织docs/src/content/en/docs下可见 agents、auth、channels、deployment、evals、memory、observability、sandbox、server、storage、studio、workflows 等类别目录与 Overview 页面的适用场景一一对应侧边栏确实是导航的权威来源docs/src/content/en/docs/sidebars.js负责主文档导航集成页的标签、路由、排序和图标元数据则由docs/src/content/en/integrations/sidebars.js维护COMPONENTS.md 要求不要把这些元数据复制进 MDX校验脚本真实存在docs/scripts/下有move-doc.ts、delete-doc.ts、validate-frontmatter.ts、validate-sidebar-docs.ts等与 AUTHORING_WORKFLOW.md 描述的命令一一对应llms-txt 抽取是可测试的行为插件目录docs/src/plugins/docusaurus-plugin-llms-txt/的测试文件验证了组件处理器、内容抽取器和 head-link 处理说明页面结构影响 llms-txt 输出这一声明有测试保障。结语DOC.md 传达的核心理念是页面结构应围绕读者的问题或任务组织而不是围绕强制模板。五种页面类型给出了起点frontmatter 与 MDX 骨架给出了落点COMPONENTS.md 与 INFORMATION_ARCHITECTURE.md 规定了组件选用与内容归属而 AUTHORING_WORKFLOW.md 保证了改动可验证、可维护。写作时以 DOC.md 为页面级主纲以 STYLEGUIDE.md 为文字级底线以仓库源码与测试为事实依据即可产出既符合 Mastra 官方规范、又对人与机器llms.txt 抽取都友好的文档页面。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考