Medusa 文档 MDX 编写模式完全指南页面元数据、代码块、版本标注与跨项目链接规范【免费下载链接】medusaThe worlds most flexible commerce platform for agents and developers项目地址: https://gitcode.com/GitHub_Trending/me/medusa本篇技术指南系统讲解 Medusa 开源仓库中文档项目的 MDX 编写模式syntax patterns其权威依据是仓库内的写作技能参考文档 mdx-patterns.md。该参考文件被book、resources、ui、user-guide、cloud五个文档项目共同遵守是维护 Medusa 官方文档时的语法基准。读完本篇你将掌握这套文档系统的页面元数据写法、代码块高亮与多包管理器标签、提示组件、版本标注规则、跨项目链接约定以及键盘快捷键组件的正确用法并能直接据此在 www/apps/ 下的任意文档项目中编写符合 CI 要求的 MDX 页面。这套 MDX 模式的定位与适用范围参考文件在写作技能中的角色在.claude/skills/writing-docs/目录下SKILL.md定义了名为writing-docs的写作技能用于在book、resources、ui、user-guide、cloud五个项目下编写和更新 Medusa 文档。该技能要求在写任何 MDX 内容之前先加载reference/mdx-patterns.md对应关系见 SKILL.md 中的表格。也就是说mdx-patterns.md 是所有 MDX 作者的第一参考文件它规定了跨五个文档项目统一的“精确语法”exact syntax。受约束的目录与红线在动手编写前需要了解这套规范背后的硬性约束同样来自 SKILL.md绝不记录ignore标记的条目TSDoc 中被ignore标注的选项、方法、参数一律跳过绝不修改自动生成目录www/apps/resources/references/、www/apps/ui/specs/components/、www/apps/api-reference/均由独立流程生成会被覆盖绝不手动运行yarn prep与yarn lint:content它们在会话结束后自动执行手动运行会破坏流水线绝不虚构 Cloudinary 截图 URLuser-guide 中拿不到截图链接时用!-- TODO: add screenshot --占位。理解这些约束才能明白后续语法规则为何如此设计例如标题里的${pageNumber}变量、generate_toc前置元数据都与yarn prep的自动注入和目录生成机制深度绑定。页面元数据每一页 MDX 的第一行标准元数据导出每一页 MDX 的第一行必须是metadata对象导出这是所有文档项目的硬性要求export const metadata { title: Page Title, } # {metadata.title}注意标题部分使用# {metadata.title}引用导出的变量而不是把标题文本直接硬编码在标题行。这样页面标题只需维护一处yarn prep等脚本也能统一处理。book 项目的${pageNumber}变量在book项目即 www/apps/book/Medusa 学习平台中标题使用自动生成的${pageNumber}变量必须始终保留它export const metadata { title: ${pageNumber} Workflows, } # {metadata.title} **CRITICAL:** Never remove ${pageNumber} from book titles. It is injected by the prep script.从仓库实测来看这一约定在真实页面中完全落地。例如 medusa-config 配置章节 的第一行就是export const metadata { title: ${pageNumber} Medusa Application Configuration, } # {metadata.title}而 book-style.md 进一步说明${pageNumber}由yarn prep自动填充新增页面时必须包含它新增页面的完整步骤是先在www/apps/book/app/learn/section/topic/page.mdx创建文件再在 www/apps/book/sidebar.mjs 的侧边栏数组中登记type: link条目最后交给yarn prep自动编号。动态注入内容的generate_toc前置元数据当页面内容不是直接写在 MDX 里而是由 React 组件动态注入时必须开启generate_toc前置元数据以便脚本为页面生成目录table of contents条目--- generate_toc: true --- import Content from ./content export const metadata { title: Product Module, } Content /generate_toc: true是告诉构建管线“这个页面的标题层级需要从组件渲染结果中提取”否则动态内容页面会缺失目录项。元数据与面向 Agent/LLM 的 Markdown 流水线值得补充的是这套“导出 metadata 标题表达式”的设计不只是为了网页渲染。在 get-clean-md.ts 中文档系统会把 MDX 解析并字符串化为提供给 Agent 与 LLM 的纯净 Markdown其中resolveExpressionsPlugin专门解析诸如{config.version.number}、{someExportedConst}这类 MDX 表达式将它们求值后替换成真实值避免占位符泄漏到给 Agent 的文档里无法静态求值的表达式会被移除。这说明规范的元数据与表达式写法直接关系到自动化文档流水线的正确性。代码块从基础写法到高亮与多标签基础代码块使用title属性标注文件路径~~~mdx外层包裹是为了在参考文档中展示字面语法实际写作时只写内层代码块ts titlesrc/workflows/my-workflow.ts import { createWorkflow } from medusajs/framework/workflows-sdk // ... title属性会在渲染后显示为代码块的文件名标签方便读者知道该把代码放到哪个文件。带高亮的代码块高亮用于吸引读者注意特定行。高亮数组必须定义在代码块之前每个条目是[行号, 变量名, 说明文字]三元组export const highlights [ [3, greetingJob, The function executed at the scheduled interval.], [4, container, Receive the Medusa container as a parameter.], [10, name, A unique name for the job.], ] ts titlesrc/jobs/hello-world.ts highlights{highlights} import { MedusaContainer } from medusajs/framework/types export default async function greetingJob(container: MedusaContainer) { const logger container.resolve(logger) logger.info(Greeting!) } export const config { name: greeting-every-minute, schedule: * * * * *, } 代码块通过highlights{highlights}引用该数组渲染时第 3、4、10 行会被标记出来并附带对应说明。这个例子本身也演示了 Medusa 的定时任务scheduled job写法默认导出接收MedusaContainer的异步函数config中的name是任务唯一名称schedule是 cron 表达式。高亮约定与 book-style.md 的要求一致书项目中的每个概念至少配一个可运行的 TypeScript 示例并用高亮标出关键行。多包管理器标签CodeTabs/CodeTab当一段命令有 npm/yarn/pnpm 等多个包管理器版本时使用docs-ui提供的CodeTabs与CodeTab组件实现见 docs-ui 的 CodeTabs 组件import { CodeTabs, CodeTab } from docs-ui CodeTabs groupnpm2yarn CodeTab labelnpm valuenpm bash npm run dev /CodeTab CodeTab labelyarn valueyarn bash yarn dev /CodeTab /CodeTabsgroupnpm2yarn让这些标签页与站内其他 npm/yarn 标签联动用户在一个地方切换包管理器其他同组标签自动跟随切换。对于存在 npm/yarn 等价命令的 bash 命令还有简写形式直接在代码块语言后加npm2yarnbash npm2yarn npm run dev 提示组件Note信息、技巧、警告与“别用”Note组件实现见 docs-ui 的 Note 组件提供四种语义默认title缺省一般性说明信息titleTip有用的技巧或快捷方式titleWarning typewarning需要小心的事项titleDont use this if typeerror明确列出该方案不适用的条件此时正文用列表逐条说明并常配合替代方案链接。Note General informational note. /Note Note titleTip A helpful tip or shortcut. /Note Note titleWarning typewarning Something to be careful about. /Note Note titleDont use this if typeerror - A condition where this approach is wrong - Another condition /Note从 book-style.md 的页面结构模板可以看到Note titleDont use Topic if typeerror是概念类章节的固定组成部分先给出 13 段概念解释再用“Dont use if”列表帮助读者判断边界最后引导到替代方案。版本标注让读者知道“什么时候开始可用”记录新选项、方法、参数或行为变更时必须附加版本标注让读者明确该能力从哪个版本开始可用。当前版本从哪来版本号统一维护在 docs-ui 的 global-config.ts它从docs-utils重新导出globalConfig拆分到docs-utils/global-config子路径是为了让非 React 消费者——如 Markdown/LLM 生成流水线和构建脚本——也能读取。真实版本数据位于 docs-utils 的 global-config.tsexport const globalConfig: PickDocsConfig, version { version: { number: 2.20.1, releaseUrl: https://github.com/medusajs/medusa/releases/tag/v2.20.1, releaseDate: 2026-09-03T09:41:28Z } }写入时的规则获取当前版本读取version.number当前仓库为2.20.1下一个版本 补丁号 1例如2.13.5→2.13.6。当变更正在被引入、尚未发布时使用下一个版本号发布链接模式按releases/tag/v{version}的标签约定拼接对应版本的发布说明地址例如v2.13.6对应版本标签 v2.13.6。三种标注形式形式一新选项/方法/参数——紧跟标题的Note块放在新条目标题之后、描述之前### myNewOption Note This option is available since Medusa v2.13.6 (release notes). /Note Description of the option...形式二行为变更——“Before Medusa v...” 放在Note内当既有行为发生改变、用户可能持有旧代码时使用Note Before Medusa v2.13.6, you did X. Now, you must do Y instead. /Note形式三表格单元格内的行内版本标注对Table组件中新增或废弃的条目在单元格内标注Table.Cell myOption (v2.13.6) /Table.Cell废弃条目则同时给出替代项Table.Cell oldOption (Deprecated v2.13.6, use newOption instead) /Table.Cell新增条目用(v{version})废弃条目用(Deprecated v{version}, use ... instead)这样版本信息可以随表格一起被检索。同时SKILL.md 的“常见错误”清单把“新增选项/方法/参数却漏写版本标注”列为第一项可见这是审查的重点。前置条件组件Prerequisites需要在页面顶部声明“读者应已具备的知识或环境”时使用docs-ui的Prerequisites组件实现见 docs-ui 的 Prerequisites 组件import { Prerequisites } from docs-ui Prerequisites items{[ { text: Medusa application set up, link: !docs!/learn/installation, }, { text: pnpm installed, link: external installation guide, }, ]} /items数组的每个对象包含text前置条件描述与link指向对应指南。注意这里混用了两种链接Medusa 内部指南用!docs!跨项目链接语法外部工具安装指南则填完整 URL。出于链接规范要求本文示例中的外部地址以占位符external installation guide表示实际写作时填写 pnpm 官方安装页的完整地址即可。跨项目链接绝不使用绝对 URLMedusa 文档按项目拆分为book文档/学习平台、resources资源与 API 参考、user-guide用户指南等页面之间互相引用时禁止使用绝对 URL必须使用特殊链接语法text → book text → resources text → user-guide!docs!前缀解析到book项目!resources!前缀解析到resources项目!user-guide!前缀解析到user-guide项目。这样做的原因是文档站部署时各项目前缀会变化用特殊前缀语法可以在构建期正确解析同时保持源文件可移植。同一项目内部的链接则使用普通相对路径[text](https://link.gitcode.com/i/ae24fa6dcaaf35ab83934149d0aba587) [text](https://link.gitcode.com/i/ae24fa6dcaaf35ab83934149d0aba587)章节分隔符---用---水平分隔线分隔文档的主要章节形成清晰的视觉与语义边界## First Section Content here. --- ## Second Section Content here.从 book-style.md 的页面模板可以看出---与##章节的组合是 book 页面概念解释 → 实现步骤 → 测试 → 实例的标准骨架。导入规则位置有严格顺序组件导入必须放在文件顶部位于 frontmatter 之后、metadata 导出之前--- generate_toc: true --- import { Prerequisites } from docs-ui import { CodeTabs, CodeTab } from docs-ui export const metadata { title: My Page, }即页面文件的元素顺序固定为frontmatter---包裹→ import 语句 →export const metadata→# {metadata.title}→ 正文。违反顺序可能导致解析错误或与yarn prep流水线冲突。图片标准 Markdown 语法 Cloudinary URLuser-guide 的界面截图使用标准 Markdown 图片语法URL 指向 Cloudinary两条硬性规则没有真实 URL 时用占位注释不要编造地址!-- TODO: add screenshot of description --绝不虚构 Cloudinary URL这也是 SKILL.md 红线清单之一。URL 通常由截图上传流程自动生成人工编造的地址必然 404。Alt 文本需要准确描述截图内容以便无障碍阅读与搜索索引。键盘快捷键Kbd与getOsShortcut需要按下的按键——Kbd组件任何需要用户按下的键名都用docs-ui的Kbd组件包裹实现见 docs-ui 的 Kbd 组件渲染为键盘键帽样式import { Kbd } from docs-ui Press KbdEnter/Kbd to confirm, or KbdEscape/Kbd to cancel.系统相关快捷键——getOsShortcutmacOS⌘ Cmd与 Windows/LinuxCtrl的主修饰键不同。当快捷键因系统而异时使用docs-ui的getOsShortcut工具让站点根据用户操作系统自动显示正确的键import { Kbd, getOsShortcut } from docs-ui Press Kbd{getOsShortcut()}/KbdKbdS/Kbd to save.按文档约定getOsShortcut()在 macOS 返回Cmd在其他平台返回Ctrl从实现看os-browser-utils.ts函数通过navigator.userAgent检测 macOSmacOS 返回⌘符号、其他平台返回Ctrl并在无navigator的环境如 SSR 首屏默认按 macOS 处理同一文件还提供了getBrowser()用于识别 Chrome/Safari/Firefox 等浏览器。规则绝不单独硬编码Cmd或Ctrl。只要快捷键涉及主修饰键就必须使用getOsShortcut()保证两个平台都被覆盖否则 Windows/Linux 用户会看到永远按不出来的 ⌘ 组合键。写作风格与常见错误清单最后mdx-patterns.md 是语法层参考而配合 SKILL.md 与 book-style.md 可以总结出这套文档体系的写作基调供编写时自查人称与语态正文使用第二人称you或祈使句禁止we、us、lets、our避免被动语态如 is created改用主动语态you create / call X to create。时态统一使用现在时The workflow runs...而非 will run。措辞禁用e.g.,改写为for example、禁用破折号—Medusa API 若指后端一律写作 Medusa backend。代码行宽代码行不超过 64 字符。组件优先使用 MDX 组件而非img或裸 HTML。只写公共 API不记录内部实现细节internal implementation details。版本标注新增选项、方法、参数必须附带版本标注ignore标记的条目一律跳过。这套模式与 Medusa 文档自动生成、Agent/LLM 消费流水线见 get-clean-md.ts深度耦合规范的 metadata 导出、版本标注、跨项目链接语法最终都会被解析成结构清晰、可检索、可引用的文档数据。理解了 mdx-patterns.md 背后的设计意图与配套约束就能在 www/apps/ 的任意文档项目中写出既符合 CI 要求、又易于机器消费的 MDX 页面。【免费下载链接】medusaThe worlds most flexible commerce platform for agents and developers项目地址: https://gitcode.com/GitHub_Trending/me/medusa创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
